factorix 0.5.0

data/lib/factorix/api/mod_info.rb

@@ -0,0 +1,166 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+
+module Factorix
+  module API
+    MODInfo = Data.define(:name, :title, :owner, :summary, :downloads_count, :category, :score, :thumbnail, :latest_release, :releases, :detail)
+
+    # MOD information from MOD Portal API
+    #
+    # Represents MOD metadata from various API endpoints:
+    # - /api/mods (list)
+    # - /api/mods/{name} (Short)
+    # - /api/mods/{name}/full (Full)
+    #
+    # @see https://wiki.factorio.com/Mod_portal_API
+    class MODInfo
+      # @!attribute [r] name
+      #   @return [String] internal MOD name (unique identifier)
+      # @!attribute [r] title
+      #   @return [String] human-readable MOD title
+      # @!attribute [r] owner
+      #   @return [String] MOD owner username
+      # @!attribute [r] summary
+      #   @return [String] short description
+      # @!attribute [r] downloads_count
+      #   @return [Integer] total number of downloads
+      # @!attribute [r] category
+      #   @return [Category] MOD category
+      # @!attribute [r] score
+      #   @return [Float] MOD score/rating
+      # @!attribute [r] thumbnail
+      #   @return [URI::HTTPS, nil] thumbnail image URL
+      # @!attribute [r] latest_release
+      #   @return [Release, nil] latest release (list API without namelist)
+      # @!attribute [r] releases
+      #   @return [Array<Release>] all releases
+      # @!attribute [r] detail
+      #   @return [Detail, nil] detailed information (Full API only)
+
+      Detail = Data.define(:changelog, :created_at, :updated_at, :last_highlighted_at, :description, :source_url, :homepage, :faq, :tags, :license, :images, :deprecated)
+      DETAIL_ALLOWED_KEYS = %i[changelog created_at updated_at last_highlighted_at description source_url homepage faq tags license images deprecated].freeze
+      private_constant :DETAIL_ALLOWED_KEYS
+
+      # Detailed MOD information from Full API endpoint
+      #
+      # @see https://wiki.factorio.com/Mod_portal_API
+      class Detail
+        # @!attribute [r] changelog
+        #   @return [String] changelog text
+        # @!attribute [r] created_at
+        #   @return [Time] creation timestamp
+        # @!attribute [r] updated_at
+        #   @return [Time] last update timestamp
+        # @!attribute [r] last_highlighted_at
+        #   @return [Time, nil] last highlighted timestamp
+        # @!attribute [r] description
+        #   @return [String] detailed description text
+        # @!attribute [r] source_url
+        #   @return [URI::HTTPS, nil] source repository URL
+        # @!attribute [r] homepage
+        #   @return [URI, String] homepage URL or string
+        # @!attribute [r] faq
+        #   @return [String] FAQ text
+        # @!attribute [r] tags
+        #   @return [Array<Tag>] tags
+        # @!attribute [r] license
+        #   @return [License, nil] license information
+        # @!attribute [r] images
+        #   @return [Array<Image>] images
+        # @!attribute [r] deprecated
+        #   @return [Boolean] deprecation status
+
+        # Create Detail from API response hash
+        #
+        # @param changelog [String, nil] changelog
+        # @param created_at [String] ISO 8601 timestamp
+        # @param updated_at [String] ISO 8601 timestamp
+        # @param last_highlighted_at [String, nil] ISO 8601 timestamp
+        # @param description [String, nil] description
+        # @param source_url [String, nil] source URL
+        # @param homepage [String] homepage URL or string
+        # @param faq [String, nil] FAQ
+        # @param tags [Array<String>, nil] tags
+        # @param license [Hash, nil] license data
+        # @param images [Array<Hash>, nil] images data
+        # @param deprecated [Boolean, nil] deprecated flag
+        # @return [Detail] new Detail instance
+        def initialize(created_at:, updated_at:, homepage:, changelog: nil, last_highlighted_at: nil, description: nil, source_url: nil, faq: nil, tags: nil, license: nil, images: nil, deprecated: nil)
+          changelog ||= ""
+          created_at = Time.parse(created_at).utc
+          updated_at = Time.parse(updated_at).utc
+          last_highlighted_at = last_highlighted_at ? Time.parse(last_highlighted_at).utc : nil
+          description ||= ""
+          source_url = parse_uri(source_url)
+          homepage = parse_uri(homepage)
+          faq ||= ""
+          tags = (tags || []).map {|tag_value| Tag.for(tag_value) }
+          license = license ? License[**license] : nil
+          images = (images || []).map {|img| Image[**img] }
+          deprecated ||= false
+
+          super
+        end
+
+        # Check if the MOD is deprecated
+        #
+        # @return [Boolean] true if deprecated
+        def deprecated? = deprecated
+
+        private def parse_uri(value)
+          return nil if value.nil? || value.empty?
+
+          URI(value)
+        rescue URI::InvalidURIError => e
+          Application[:logger].warn("Skipping invalid URI '#{value}': #{e.message}")
+          nil
+        end
+      end
+
+      # Create MODInfo from API response hash
+      #
+      # @param name [String] MOD name
+      # @param title [String] MOD title
+      # @param owner [String] owner username
+      # @param summary [String, nil] summary
+      # @param downloads_count [Integer] download count
+      # @param category [String, nil] category value
+      # @param score [Float, nil] score
+      # @param thumbnail [String, nil] thumbnail path
+      # @param latest_release [Hash, nil] latest release data
+      # @param releases [Array<Hash>, nil] releases data
+      # @param detail [Hash, nil] detail data
+      # @return [MODInfo] new MODInfo instance
+      def initialize(name:, title:, owner:, downloads_count:, summary: nil, category: nil, score: nil, thumbnail: nil, latest_release: nil, releases: nil, **detail_fields)
+        summary ||= ""
+        category = Category.for(category || "")
+        score ||= 0.0
+        thumbnail = thumbnail ? build_thumbnail_uri(thumbnail) : nil
+        latest_release = latest_release ? Release[**latest_release] : nil
+        releases = (releases || []).filter_map {|r|
+          # NOTE: begin is required because {...} blocks cannot use rescue directly
+          begin
+            Release[**r]
+          rescue RangeError => e
+            # Skip releases with invalid version numbers
+            Application[:logger].warn("Skipping release #{name}@#{r[:version]}: #{e.message}")
+            nil
+          end
+        }
+
+        # Filter detail_fields to only include keys that Detail.new accepts
+        # Exclude deprecated fields like github_path
+        detail = Detail.new(**detail_fields.slice(*DETAIL_ALLOWED_KEYS)) if all_required_detail_fields?(detail_fields)
+
+        super(name:, title:, owner:, summary:, downloads_count:, category:, score:, thumbnail:, latest_release:, releases:, detail:)
+      end
+
+      private def build_thumbnail_uri(path) = URI("https://assets-mod.factorio.com#{path}")
+
+      # Check if detail_fields contains all required fields for Detail
+      private def all_required_detail_fields?(detail_fields) = %i[created_at updated_at homepage].all? {|field| detail_fields.key?(field) }
+    end
+  end
+end

data/lib/factorix/api/mod_management_api.rb

@@ -0,0 +1,237 @@
+# frozen_string_literal: true
+
+require "dry/events"
+require "json"
+require "uri"
+
+module Factorix
+  module API
+    # API client for MOD management operations (upload, publish, edit)
+    #
+    # Requires API key authentication via APICredential.
+    # Uses api_credential lazy loading to avoid early environment variable evaluation.
+    class MODManagementAPI
+      # NOTE: api_credential is NOT imported to avoid early evaluation errors
+      # when FACTORIO_API_KEY environment variable is not set.
+      # It's resolved lazily via reader method instead.
+      # @!parse
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      #   # @return [Transfer::Uploader]
+      #   attr_reader :uploader
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      include Import[:uploader, :logger, client: :http_client]
+      include Dry::Events::Publisher[:mod_management]
+
+      register_event("mod.changed")
+
+      BASE_URL = "https://mods.factorio.com"
+      private_constant :BASE_URL
+
+      # Metadata fields allowed in finish_upload (only for init_publish scenario)
+      ALLOWED_UPLOAD_METADATA = %w[description category license source_url].freeze
+      private_constant :ALLOWED_UPLOAD_METADATA
+
+      # Metadata fields allowed in edit_details
+      ALLOWED_EDIT_METADATA = %w[description summary title category tags license homepage source_url faq deprecated].freeze
+      private_constant :ALLOWED_EDIT_METADATA
+
+      # Initialize with thread-safe credential loading
+      #
+      # @param args [Hash] dependency injection arguments
+      def initialize(...)
+        super
+        @api_credential_mutex = Mutex.new
+      end
+
+      # Initialize new MOD publication
+      #
+      # @param mod_name [String] the MOD name
+      # @return [URI::HTTPS] upload URL
+      # @raise [HTTPClientError] for 4xx errors (e.g., MOD already exists)
+      # @raise [HTTPServerError] for 5xx errors
+      def init_publish(mod_name)
+        uri = URI.join(BASE_URL, "/api/v2/mods/init_publish")
+        body = URI.encode_www_form({mod: mod_name})
+
+        logger.info("Initializing MOD publication", mod: mod_name)
+        response = client.post(uri, body:, headers: build_auth_header, content_type: "application/x-www-form-urlencoded")
+
+        parse_upload_url(response)
+      end
+
+      # Initialize update to existing MOD
+      #
+      # @param mod_name [String] the MOD name
+      # @return [URI::HTTPS] upload URL
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      # @raise [HTTPClientError] for other 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def init_upload(mod_name)
+        uri = URI.join(BASE_URL, "/api/v2/mods/releases/init_upload")
+        body = URI.encode_www_form({mod: mod_name})
+
+        logger.info("Initializing MOD upload", mod: mod_name)
+        response = client.post(uri, body:, headers: build_auth_header, content_type: "application/x-www-form-urlencoded")
+
+        parse_upload_url(response)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{mod_name}' not found on portal"
+      end
+
+      # Complete upload (works for both publish and update scenarios)
+      #
+      # @param mod_name [String] the MOD name
+      # @param upload_url [URI::HTTPS] the upload URL from init_publish or init_upload
+      # @param file_path [Pathname] path to MOD zip file
+      # @param metadata [Hash] optional metadata (only used for init_publish)
+      # @option metadata [String] :description Markdown description
+      # @option metadata [String] :category MOD category
+      # @option metadata [String] :license License identifier
+      # @option metadata [String] :source_url Repository URL
+      # @return [void]
+      # @raise [HTTPClientError] for 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def finish_upload(mod_name, upload_url, file_path, **metadata)
+        validate_metadata!(metadata, ALLOWED_UPLOAD_METADATA, "finish_upload")
+
+        logger.info("Uploading MOD file", mod: mod_name, file: file_path.to_s, metadata_count: metadata.size)
+
+        fields = metadata.transform_keys(&:to_s)
+
+        uploader.upload(upload_url, file_path, fields:)
+        logger.info("Upload completed successfully", mod: mod_name)
+        publish("mod.changed", mod: mod_name)
+      end
+
+      # Edit MOD details (for post-upload metadata changes)
+      #
+      # @param mod_name [String] the MOD name
+      # @param metadata [Hash] metadata to update
+      # @option metadata [String] :description Markdown description
+      # @option metadata [String] :summary Brief description
+      # @option metadata [String] :title MOD title
+      # @option metadata [String] :category MOD category
+      # @option metadata [Array<String>] :tags Array of tags
+      # @option metadata [String] :license License identifier
+      # @option metadata [String] :homepage Homepage URL
+      # @option metadata [String] :source_url Repository URL
+      # @option metadata [String] :faq FAQ text
+      # @option metadata [Boolean] :deprecated Deprecation flag
+      # @return [void]
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      # @raise [HTTPClientError] for other 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def edit_details(mod_name, **metadata)
+        validate_metadata!(metadata, ALLOWED_EDIT_METADATA, "edit_details")
+
+        uri = URI.join(BASE_URL, "/api/v2/mods/edit_details")
+
+        # URI.encode_www_form handles arrays as multiple params (tags=a&tags=b)
+        form_data = {mod: mod_name, **metadata}.transform_keys(&:to_s)
+        body = URI.encode_www_form(form_data)
+
+        logger.info("Editing MOD details", mod: mod_name, fields: metadata.keys)
+        client.post(uri, body:, headers: build_auth_header, content_type: "application/x-www-form-urlencoded")
+        logger.info("Edit completed successfully", mod: mod_name)
+        publish("mod.changed", mod: mod_name)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{mod_name}' not found on portal"
+      end
+
+      # Initialize image upload for a MOD
+      #
+      # @param mod_name [String] the MOD name
+      # @return [URI::HTTPS] upload URL
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      # @raise [HTTPClientError] for other 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def init_image_upload(mod_name)
+        uri = URI.join(BASE_URL, "/api/v2/mods/images/add")
+        body = URI.encode_www_form({mod: mod_name})
+
+        logger.info("Initializing image upload", mod: mod_name)
+        response = client.post(uri, body:, headers: build_auth_header, content_type: "application/x-www-form-urlencoded")
+
+        parse_upload_url(response)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{mod_name}' not found on portal"
+      end
+
+      # Complete image upload
+      #
+      # @param mod_name [String] the MOD name
+      # @param upload_url [URI::HTTPS] the upload URL from init_image_upload
+      # @param image_file [Pathname] path to image file
+      # @return [Hash] parsed response with image info (id, url, thumbnail)
+      # @raise [HTTPClientError] for 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def finish_image_upload(mod_name, upload_url, image_file)
+        logger.info("Uploading image file", mod: mod_name, file: image_file.to_s)
+
+        response = uploader.upload(upload_url, image_file, field_name: "image")
+        data = JSON.parse(response.body)
+
+        logger.info("Image upload completed successfully", mod: mod_name, image_id: data["id"])
+        publish("mod.changed", mod: mod_name)
+        data
+      rescue JSON::ParserError => e
+        raise HTTPError, "Invalid JSON response: #{e.message}"
+      end
+
+      # Edit MOD's image list
+      #
+      # @param mod_name [String] the MOD name
+      # @param image_ids [Array<String>] array of image IDs (SHA1 hashes)
+      # @return [void]
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      # @raise [HTTPClientError] for other 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      def edit_images(mod_name, image_ids)
+        raise ArgumentError, "image_ids must be an array" unless image_ids.is_a?(Array)
+
+        uri = URI.join(BASE_URL, "/api/v2/mods/images/edit")
+
+        form_data = {mod: mod_name, images: image_ids.join(",")}
+        body = URI.encode_www_form(form_data)
+
+        logger.info("Editing MOD images", mod: mod_name, image_count: image_ids.size)
+        client.post(uri, body:, headers: build_auth_header, content_type: "application/x-www-form-urlencoded")
+        logger.info("Images updated successfully", mod: mod_name)
+        publish("mod.changed", mod: mod_name)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{mod_name}' not found on portal"
+      end
+
+      private def api_credential
+        return @api_credential if defined?(@api_credential)
+
+        @api_credential_mutex.synchronize do
+          @api_credential ||= Application[:api_credential]
+        end
+      end
+
+      private def build_auth_header
+        {"Authorization" => "Bearer #{api_credential.api_key}"}
+      end
+
+      private def validate_metadata!(metadata, allowed_keys, context)
+        return if metadata.empty?
+
+        invalid_keys = metadata.keys.map(&:to_s) - allowed_keys
+        return if invalid_keys.empty?
+
+        raise ArgumentError, "Invalid metadata for #{context}: #{invalid_keys.join(", ")}. Allowed keys: #{allowed_keys.join(", ")}"
+      end
+
+      private def parse_upload_url(response)
+        data = JSON.parse(response.body)
+        url_string = data["upload_url"] or raise HTTPError, "Missing upload_url in response"
+        URI(url_string)
+      rescue JSON::ParserError => e
+        raise HTTPError, "Invalid JSON response: #{e.message}"
+      end
+    end
+  end
+end

data/lib/factorix/api/mod_portal_api.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require "erb"
+require "json"
+require "tempfile"
+require "uri"
+
+module Factorix
+  module API
+    # API client for retrieving MOD list and details without authentication
+    #
+    # Corresponds to: https://wiki.factorio.com/Mod_portal_API
+    class MODPortalAPI
+      # @!parse
+      #   # @return [Dry::Logger::Dispatcher]
+      #   attr_reader :logger
+      #   # @return [Cache::FileSystem]
+      #   attr_reader :cache
+      #   # @return [HTTP::Client]
+      #   attr_reader :client
+      include Import[:logger, cache: :api_cache, client: :api_http_client]
+
+      BASE_URL = "https://mods.factorio.com"
+      private_constant :BASE_URL
+
+      # Retrieve MOD list with optional filters
+      #
+      # @param namelist [Array<String>] MOD names to filter (positional arguments, sorted for cache consistency)
+      # @param hide_deprecated [Boolean, nil] hide deprecated MODs
+      # @param page [Integer, nil] page number (1-based)
+      # @param page_size [Integer, String, nil] number of results per page (positive integer or "max")
+      # @param sort [String, nil] sort field (name, created_at, updated_at)
+      # @param sort_order [String, nil] sort order (asc, desc)
+      # @param version [String, nil] Factorio version filter
+      # @return [Hash{Symbol => untyped}] parsed JSON response with :results and :pagination keys
+      def get_mods(*namelist, hide_deprecated: nil, page: nil, page_size: nil, sort: nil, sort_order: nil, version: nil)
+        validate_page_size!(page_size) if page_size
+        validate_sort!(sort) if sort
+        validate_sort_order!(sort_order) if sort_order
+        validate_version!(version) if version
+
+        params = {namelist: namelist.sort, hide_deprecated:, page:, page_size:, sort:, sort_order:, version:}
+        params.reject! {|_k, v| v.is_a?(Array) && v.empty? }
+        params.compact!
+        logger.debug "Fetching MOD list: params=#{params.inspect}"
+        uri = build_uri("/api/mods", **params)
+        fetch_with_cache(uri)
+      end
+
+      # Retrieve basic information for a specific MOD
+      #
+      # @param name [String] MOD name
+      # @return [Hash{Symbol => untyped}] parsed JSON response with MOD metadata and releases
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      def get_mod(name)
+        logger.debug "Fetching MOD: name=#{name}"
+        encoded_name = ERB::Util.url_encode(name)
+        uri = build_uri("/api/mods/#{encoded_name}")
+        fetch_with_cache(uri)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{name}' not found on portal"
+      end
+
+      # Retrieve detailed information for a specific MOD
+      #
+      # @param name [String] MOD name
+      # @return [Hash{Symbol => untyped}] parsed JSON response with full MOD details including dependencies
+      # @raise [MODNotOnPortalError] if MOD not found on portal
+      def get_mod_full(name)
+        logger.debug "Fetching full MOD info: name=#{name}"
+        encoded_name = ERB::Util.url_encode(name)
+        uri = build_uri("/api/mods/#{encoded_name}/full")
+        fetch_with_cache(uri)
+      rescue HTTPNotFoundError => e
+        raise MODNotOnPortalError, e.api_message || "MOD '#{name}' not found on portal"
+      end
+
+      # Event handler for mod.changed event
+      # Invalidates cached MOD information when a MOD is modified on the portal
+      #
+      # @param event [Dry::Events::Event] event with mod payload
+      # @return [void]
+      def on_mod_changed(event)
+        mod_name = event[:mod]
+        encoded_name = ERB::Util.url_encode(mod_name)
+
+        # Invalidate get_mod cache
+        mod_uri = build_uri("/api/mods/#{encoded_name}")
+        mod_key = cache.key_for(mod_uri.to_s)
+        cache.with_lock(mod_key) { cache.delete(mod_key) }
+
+        # Invalidate get_mod_full cache
+        full_uri = build_uri("/api/mods/#{encoded_name}/full")
+        full_key = cache.key_for(full_uri.to_s)
+        cache.with_lock(full_key) { cache.delete(full_key) }
+
+        logger.debug("Invalidated cache for MOD", mod: mod_name)
+      end
+
+      private def build_uri(path, **params)
+        URI.join(BASE_URL, path).tap {|uri| uri.query = URI.encode_www_form(params.sort.to_h) unless params.empty? }
+      end
+
+      # Fetch data with cache support
+      #
+      # @param uri [URI::HTTPS] URI to fetch
+      # @return [Hash{Symbol => untyped}] parsed JSON response with symbolized keys
+      private def fetch_with_cache(uri)
+        key = cache.key_for(uri.to_s)
+
+        cached = cache.read(key, encoding: "UTF-8")
+        if cached
+          logger.debug("API cache hit", uri: uri.to_s)
+          return JSON.parse(cached, symbolize_names: true)
+        end
+
+        logger.debug("API cache miss", uri: uri.to_s)
+        response_body = fetch_from_api(uri)
+
+        store_in_cache(key, response_body)
+
+        JSON.parse(response_body, symbolize_names: true)
+      end
+
+      # Fetch data from API via HTTP
+      #
+      # @param uri [URI::HTTPS] URI to fetch
+      # @return [String] response body
+      # @raise [HTTPClientError] for 4xx errors
+      # @raise [HTTPServerError] for 5xx errors
+      private def fetch_from_api(uri)
+        logger.info("Fetching from API", uri: uri.to_s)
+        response = client.get(uri)
+        logger.info("API response", code: response.code, size_bytes: response.body.bytesize)
+        response.body
+      end
+
+      # Store response body in cache via temporary file
+      #
+      # @param key [String] cache key
+      # @param data [String] response body
+      # @return [void]
+      private def store_in_cache(key, data)
+        temp_file = Tempfile.new("cache")
+        begin
+          temp_file.write(data)
+          temp_file.close
+          cache.store(key, Pathname(temp_file.path))
+          logger.debug("Stored API response in cache", key:)
+        ensure
+          temp_file.unlink
+        end
+      end
+
+      # Validate page_size parameter
+      #
+      # @param page_size [Integer, String] page size value
+      # @return [void]
+      # @raise [ArgumentError] if page_size is invalid
+      private def validate_page_size!(page_size)
+        return if page_size == "max"
+        return if page_size.is_a?(Integer) && page_size.positive?
+
+        raise ArgumentError, "page_size must be a positive integer or 'max', got: #{page_size.inspect}"
+      end
+
+      # Validate sort parameter
+      #
+      # @param sort [String] sort field name
+      # @return [void]
+      # @raise [ArgumentError] if sort is invalid
+      private def validate_sort!(sort)
+        valid_sorts = %w[name created_at updated_at]
+        return if valid_sorts.include?(sort)
+
+        raise ArgumentError, "sort must be one of #{valid_sorts.join(", ")}, got: #{sort.inspect}"
+      end
+
+      # Validate sort_order parameter
+      #
+      # @param sort_order [String] sort order
+      # @return [void]
+      # @raise [ArgumentError] if sort_order is invalid
+      private def validate_sort_order!(sort_order)
+        valid_orders = %w[asc desc]
+        return if valid_orders.include?(sort_order)
+
+        raise ArgumentError, "sort_order must be one of #{valid_orders.join(", ")}, got: #{sort_order.inspect}"
+      end
+
+      # Validate version parameter
+      #
+      # @param version [String] Factorio version
+      # @return [void]
+      # @raise [ArgumentError] if version is invalid
+      private def validate_version!(version)
+        valid_versions = %w[0.13 0.14 0.15 0.16 0.17 0.18 1.0 1.1 2.0]
+        return if valid_versions.include?(version)
+
+        raise ArgumentError, "version must be one of #{valid_versions.join(", ")}, got: #{version.inspect}"
+      end
+    end
+  end
+end

data/lib/factorix/api/release.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "time"
+require "uri"
+
+module Factorix
+  module API
+    Release = Data.define(:download_url, :file_name, :info_json, :released_at, :version, :sha1, :feature_flags)
+
+    # Release object from MOD Portal API
+    #
+    # Represents a specific version/release of a MOD
+    #
+    # @see https://wiki.factorio.com/Mod_portal_API#Releases
+    class Release
+      # @!attribute [r] download_url
+      #   @return [URI::HTTPS] absolute URL for downloading this release
+      # @!attribute [r] file_name
+      #   @return [String] file name of the release archive
+      # @!attribute [r] info_json
+      #   @return [Hash] info.json metadata from the MOD
+      # @!attribute [r] released_at
+      #   @return [Time] release timestamp in UTC
+      # @!attribute [r] version
+      #   @return [MODVersion] MOD version object
+      # @!attribute [r] sha1
+      #   @return [String] SHA1 checksum of the release file
+      # @!attribute [r] feature_flags
+      #   @return [Array<String>] list of enabled feature flags
+
+      # Create Release from API response hash
+      #
+      # @param download_url [String] relative download URL path
+      # @param file_name [String] release file name
+      # @param info_json [Hash] info.json metadata
+      # @param released_at [String] ISO 8601 timestamp
+      # @param version [String] version string in "X.Y.Z" format
+      # @param sha1 [String] SHA1 checksum
+      # @param feature_flags [Array<String>] list of enabled feature flags (defaults to empty array)
+      # @return [Release] new Release instance
+      def initialize(download_url:, file_name:, info_json:, released_at:, version:, sha1:, feature_flags: [])
+        download_url = URI("https://mods.factorio.com#{download_url}")
+        released_at = Time.parse(released_at).utc
+        version = MODVersion.from_string(version)
+        super
+      end
+    end
+  end
+end