reve_ai 0.1.0

data/lib/reve_ai/http/client.rb

@@ -0,0 +1,208 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+
+module ReveAI
+  # HTTP layer for API communication.
+  module HTTP
+    # Low-level HTTP client using Faraday.
+    #
+    # Handles connection management, request/response processing, error handling,
+    # and automatic retries for transient failures.
+    #
+    # @api private
+    class Client
+      # @return [Hash{Integer => Class}] Mapping of HTTP status codes to error classes
+      ERROR_CODE_MAP = {
+        400 => BadRequestError,
+        401 => UnauthorizedError,
+        402 => InsufficientCreditsError,
+        403 => ForbiddenError,
+        404 => NotFoundError,
+        422 => UnprocessableEntityError,
+        429 => RateLimitError
+      }.freeze
+
+      # @return [Array<Integer>] HTTP status codes that trigger automatic retry
+      RETRY_STATUSES = [429, 500, 502, 503, 504].freeze
+
+      # @return [Configuration] Configuration instance for this client
+      attr_reader :configuration
+
+      # Creates a new HTTP client.
+      #
+      # @param configuration [Configuration] Configuration instance
+      # @api private
+      def initialize(configuration)
+        @configuration = configuration
+      end
+
+      # Makes a POST request to the API.
+      #
+      # @param path [String] API endpoint path (e.g., "/v1/image/create")
+      # @param body [Hash] Request body to send as JSON
+      #
+      # @return [Response] Parsed API response
+      #
+      # @raise [TimeoutError] if request times out
+      # @raise [ConnectionError] if connection fails
+      # @raise [NetworkError] for other network errors
+      # @raise [BadRequestError] on 400 responses
+      # @raise [UnauthorizedError] on 401 responses
+      # @raise [InsufficientCreditsError] on 402 responses
+      # @raise [ForbiddenError] on 403 responses
+      # @raise [NotFoundError] on 404 responses
+      # @raise [UnprocessableEntityError] on 422 responses
+      # @raise [RateLimitError] on 429 responses
+      # @raise [ServerError] on 5xx responses
+      #
+      # @api private
+      def post(path, body = {})
+        normalized_path = path.sub(%r{^/}, "")
+        response = connection.post(normalized_path) { |req| req.body = JSON.generate(body) }
+        handle_response(response)
+      rescue Faraday::TimeoutError => e
+        raise TimeoutError, "Request timed out: #{e.message}"
+      rescue Faraday::ConnectionFailed => e
+        handle_connection_failed(e)
+      rescue Faraday::Error => e
+        raise NetworkError, "Network error: #{e.message}"
+      end
+
+      private
+
+      # Handles connection failed errors.
+      #
+      # Distinguishes between timeout errors (which may appear as connection failures)
+      # and actual connection failures.
+      #
+      # @param error [Faraday::ConnectionFailed] The connection error
+      # @raise [TimeoutError] if error indicates timeout
+      # @raise [ConnectionError] otherwise
+      # @api private
+      def handle_connection_failed(error)
+        raise TimeoutError, "Request timed out: #{error.message}" if error.message.include?("execution expired")
+
+        raise ConnectionError, "Connection failed: #{error.message}"
+      end
+
+      # Returns the Faraday connection, creating it if needed.
+      #
+      # @return [Faraday::Connection] Configured Faraday connection
+      # @api private
+      def connection
+        @connection ||= build_connection
+      end
+
+      # Builds a new Faraday connection with all middleware.
+      #
+      # @return [Faraday::Connection] New connection instance
+      # @api private
+      def build_connection
+        Faraday.new(url: configuration.base_url) do |conn|
+          configure_retry(conn)
+          configure_headers(conn)
+          configure_timeouts(conn)
+          configure_logging(conn)
+          conn.adapter Faraday.default_adapter
+        end
+      end
+
+      # Configures retry middleware.
+      #
+      # @param conn [Faraday::Connection] Connection to configure
+      # @api private
+      def configure_retry(conn)
+        conn.request :retry, max: configuration.max_retries, interval: 0.5,
+                             backoff_factor: 2, retry_statuses: RETRY_STATUSES, methods: [:post]
+      end
+
+      # Configures request headers.
+      #
+      # @param conn [Faraday::Connection] Connection to configure
+      # @api private
+      def configure_headers(conn)
+        conn.headers["Authorization"] = "Bearer #{configuration.api_key}"
+        conn.headers["Content-Type"] = "application/json"
+        conn.headers["Accept"] = "application/json"
+        conn.headers["User-Agent"] = user_agent
+      end
+
+      # Configures connection and read timeouts.
+      #
+      # @param conn [Faraday::Connection] Connection to configure
+      # @api private
+      def configure_timeouts(conn)
+        conn.options.timeout = configuration.timeout
+        conn.options.open_timeout = configuration.open_timeout
+      end
+
+      # Configures response logging if debug mode is enabled.
+      #
+      # @param conn [Faraday::Connection] Connection to configure
+      # @api private
+      def configure_logging(conn)
+        conn.response :logger, configuration.logger if configuration.debug && configuration.logger
+      end
+
+      # Returns the User-Agent header value.
+      #
+      # @return [String] User-Agent string
+      # @api private
+      def user_agent
+        "reve-ai-ruby/#{ReveAI::VERSION} Ruby/#{RUBY_VERSION}"
+      end
+
+      # Processes the HTTP response.
+      #
+      # @param response [Faraday::Response] Raw Faraday response
+      # @return [Response] Wrapped response on success
+      # @raise [APIError] on error responses
+      # @api private
+      def handle_response(response)
+        body = parse_body(response.body)
+        return build_success_response(response, body) if response.status.between?(200, 299)
+
+        raise_api_error(response.status, body, response.headers.to_h)
+      end
+
+      # Builds a successful response object.
+      #
+      # @param response [Faraday::Response] Raw response
+      # @param body [Hash] Parsed body
+      # @return [Response] Response wrapper
+      # @api private
+      def build_success_response(response, body)
+        Response.new(status: response.status, headers: response.headers.to_h, body: body)
+      end
+
+      # Parses the response body as JSON.
+      #
+      # @param body [String, nil] Raw response body
+      # @return [Hash] Parsed body, or empty hash if nil/empty
+      # @api private
+      def parse_body(body)
+        return {} if body.nil? || body.empty?
+
+        JSON.parse(body, symbolize_names: true)
+      rescue JSON::ParserError
+        { raw: body }
+      end
+
+      # Raises the appropriate API error for a status code.
+      #
+      # @param status [Integer] HTTP status code
+      # @param body [Hash] Parsed response body
+      # @param headers [Hash] Response headers
+      # @raise [APIError] Appropriate error subclass
+      # @api private
+      def raise_api_error(status, body, headers)
+        error_class = ERROR_CODE_MAP[status] || (status >= 500 ? ServerError : APIError)
+        message = body[:message] || body[:error] || "Unknown error"
+        raise error_class.new(message, status: status, body: body, headers: headers)
+      end
+    end
+  end
+end

data/lib/reve_ai/resources/base.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # API resource classes.
+  #
+  # Each resource class provides methods for a related set of API operations.
+  module Resources
+    # Base class for API resources with common validation methods.
+    #
+    # Provides HTTP client access and input validation for all resource classes.
+    #
+    # @abstract Subclass and implement endpoint-specific methods
+    # @api private
+    class Base
+      # @return [Client] The client instance for this resource
+      attr_reader :client
+
+      # Creates a new resource instance.
+      #
+      # @param client [Client] The API client
+      # @api private
+      def initialize(client)
+        @client = client
+      end
+
+      protected
+
+      # Returns the HTTP client for making requests.
+      #
+      # @return [HTTP::Client] HTTP client instance
+      # @api private
+      def http_client
+        client.http_client
+      end
+
+      # Returns the client configuration.
+      #
+      # @return [Configuration] Configuration instance
+      # @api private
+      def configuration
+        client.configuration
+      end
+
+      # Makes a POST request to the API.
+      #
+      # @param path [String] API endpoint path
+      # @param body [Hash] Request body
+      # @return [Response] API response
+      # @api private
+      def post(path, body = {})
+        http_client.post(path, body)
+      end
+
+      # Validates a text prompt.
+      #
+      # @param prompt [String] The prompt to validate
+      # @param field_name [String] Name for error messages (default: "Prompt")
+      # @raise [ValidationError] if prompt is nil, empty, or exceeds max length
+      # @api private
+      def validate_prompt!(prompt, field_name: "Prompt")
+        raise ValidationError, "#{field_name} is required" if prompt.nil? || prompt.empty?
+
+        max_length = Configuration::MAX_PROMPT_LENGTH
+        return unless prompt.length > max_length
+
+        raise ValidationError, "#{field_name} exceeds maximum length of #{max_length} characters"
+      end
+
+      # Validates an aspect ratio value.
+      #
+      # @param aspect_ratio [String, nil] The aspect ratio to validate
+      # @raise [ValidationError] if aspect ratio is invalid
+      # @api private
+      def validate_aspect_ratio!(aspect_ratio)
+        return if aspect_ratio.nil?
+
+        valid_ratios = Configuration::VALID_ASPECT_RATIOS
+        return if valid_ratios.include?(aspect_ratio)
+
+        raise ValidationError, "Invalid aspect_ratio '#{aspect_ratio}'. Must be one of: #{valid_ratios.join(", ")}"
+      end
+
+      # Validates a single reference image.
+      #
+      # @param image [String] Base64 encoded image data
+      # @raise [ValidationError] if image is nil or empty
+      # @api private
+      def validate_reference_image!(image)
+        raise ValidationError, "Reference image is required" if image.nil? || image.empty?
+      end
+
+      # Validates an array of reference images.
+      #
+      # @param images [Array<String>] Array of base64 encoded images
+      # @raise [ValidationError] if images is nil, empty, exceeds max, or contains empty elements
+      # @api private
+      def validate_reference_images!(images)
+        raise ValidationError, "Reference images are required" if images.nil? || images.empty?
+
+        max_images = Configuration::MAX_REFERENCE_IMAGES
+        raise ValidationError, "Maximum #{max_images} reference images allowed" if images.length > max_images
+
+        images.each_with_index do |image, index|
+          raise ValidationError, "Reference image at index #{index} is empty" if image.nil? || image.empty?
+        end
+      end
+    end
+  end
+end

data/lib/reve_ai/resources/images.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module ReveAI
+  module Resources
+    # Image generation, editing, and remixing operations.
+    #
+    # Provides methods for creating images from text prompts, editing existing
+    # images, and remixing multiple reference images into new compositions.
+    #
+    # @example Generate an image from text
+    #   client = ReveAI::Client.new(api_key: "your-key")
+    #   result = client.images.create(
+    #     prompt: "A sunset over mountains with a lake in the foreground",
+    #     aspect_ratio: "16:9"
+    #   )
+    #   puts result.base64 # Base64 encoded PNG
+    #
+    # @example Edit an existing image
+    #   result = client.images.edit(
+    #     edit_instruction: "Make the sky more dramatic with storm clouds",
+    #     reference_image: base64_encoded_original
+    #   )
+    #
+    # @example Remix multiple images
+    #   result = client.images.remix(
+    #     prompt: "Combine the style of <img>1</img> with the subject of <img>2</img>",
+    #     reference_images: [style_image_base64, subject_image_base64]
+    #   )
+    #
+    # @note All images are returned as base64 encoded PNG data.
+    # @see https://api.reve.com/console/docs Reve API Documentation
+    class Images < Base
+      # @return [String] API endpoint for image creation
+      CREATE_ENDPOINT = "/v1/image/create"
+
+      # @return [String] API endpoint for image editing
+      EDIT_ENDPOINT = "/v1/image/edit"
+
+      # @return [String] API endpoint for image remixing
+      REMIX_ENDPOINT = "/v1/image/remix"
+
+      # Generates an image from a text prompt.
+      #
+      # @param prompt [String] Text description of the desired image (max 2560 chars)
+      # @param aspect_ratio [String, nil] Output aspect ratio (defaults to API default)
+      # @param version [String, nil] Model version to use (defaults to "latest")
+      #
+      # @option aspect_ratio [String] "16:9" Widescreen landscape
+      # @option aspect_ratio [String] "9:16" Portrait (phone)
+      # @option aspect_ratio [String] "3:2" Classic landscape
+      # @option aspect_ratio [String] "2:3" Classic portrait
+      # @option aspect_ratio [String] "4:3" Standard landscape
+      # @option aspect_ratio [String] "3:4" Standard portrait
+      # @option aspect_ratio [String] "1:1" Square
+      #
+      # @return [ImageResponse] Response containing base64 encoded image
+      #
+      # @raise [ValidationError] if prompt is empty or exceeds max length
+      # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [BadRequestError] if API rejects the request
+      # @raise [UnauthorizedError] if API key is invalid
+      # @raise [InsufficientCreditsError] if account has no credits
+      # @raise [RateLimitError] if rate limit is exceeded
+      #
+      # @example Basic usage
+      #   result = client.images.create(prompt: "A cat wearing a top hat")
+      #
+      # @example With aspect ratio
+      #   result = client.images.create(
+      #     prompt: "A panoramic mountain landscape",
+      #     aspect_ratio: "16:9"
+      #   )
+      #
+      # @example Save to file
+      #   result = client.images.create(prompt: "A sunset")
+      #   File.binwrite("image.png", Base64.decode64(result.base64))
+      #
+      # @see https://api.reve.com/console/docs#/Image/create_v1_image_create_post
+      def create(prompt:, aspect_ratio: nil, version: nil)
+        validate_prompt!(prompt)
+        validate_aspect_ratio!(aspect_ratio)
+
+        body = { prompt: prompt }
+        body[:aspect_ratio] = aspect_ratio if aspect_ratio
+        body[:version] = version if version
+
+        response = post(CREATE_ENDPOINT, body)
+        ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
+      end
+
+      # Edits an existing image using text instructions.
+      #
+      # @param edit_instruction [String] Text description of how to edit the image (max 2560 chars)
+      # @param reference_image [String] Base64 encoded image to edit
+      # @param aspect_ratio [String, nil] Output aspect ratio (defaults to reference image ratio)
+      # @param version [String, nil] Model version to use (defaults to "latest")
+      #
+      # @return [ImageResponse] Response containing base64 encoded edited image
+      #
+      # @raise [ValidationError] if edit_instruction is empty or exceeds max length
+      # @raise [ValidationError] if reference_image is empty
+      # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [UnprocessableEntityError] if reference_image is not valid base64
+      # @raise [BadRequestError] if API rejects the request
+      # @raise [UnauthorizedError] if API key is invalid
+      #
+      # @example Change colors
+      #   result = client.images.edit(
+      #     edit_instruction: "Change the car color from red to blue",
+      #     reference_image: original_image_base64
+      #   )
+      #
+      # @example Add elements
+      #   result = client.images.edit(
+      #     edit_instruction: "Add a rainbow in the sky",
+      #     reference_image: landscape_base64
+      #   )
+      #
+      # @see https://api.reve.com/console/docs#/Image/edit_v1_image_edit_post
+      def edit(edit_instruction:, reference_image:, aspect_ratio: nil, version: nil)
+        validate_prompt!(edit_instruction, field_name: "Edit instruction")
+        validate_reference_image!(reference_image)
+
+        body = { edit_instruction: edit_instruction, reference_image: reference_image }
+        body[:aspect_ratio] = aspect_ratio if aspect_ratio
+        body[:version] = version if version
+
+        response = post(EDIT_ENDPOINT, body)
+        ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
+      end
+
+      # Creates a new image by remixing multiple reference images.
+      #
+      # Use `<img>N</img>` tags in the prompt to reference specific images,
+      # where N is the 1-based index into the reference_images array.
+      #
+      # @param prompt [String] Text description with optional image references (max 2560 chars)
+      # @param reference_images [Array<String>] Array of base64 encoded images (1-6 images)
+      # @param aspect_ratio [String, nil] Output aspect ratio (defaults to model's choice)
+      # @param version [String, nil] Model version to use (defaults to "latest")
+      #
+      # @return [ImageResponse] Response containing base64 encoded remixed image
+      #
+      # @raise [ValidationError] if prompt is empty or exceeds max length
+      # @raise [ValidationError] if reference_images is empty or exceeds 6 images
+      # @raise [ValidationError] if any reference image is empty
+      # @raise [ValidationError] if aspect_ratio is invalid
+      # @raise [BadRequestError] if API rejects the request
+      #
+      # @example Combine two images
+      #   result = client.images.remix(
+      #     prompt: "Combine the landscape from <img>1</img> with the sky from <img>2</img>",
+      #     reference_images: [landscape_base64, sky_base64]
+      #   )
+      #
+      # @example Style transfer
+      #   result = client.images.remix(
+      #     prompt: "Apply the artistic style of <img>1</img> to the photo <img>2</img>",
+      #     reference_images: [artwork_base64, photo_base64]
+      #   )
+      #
+      # @example Multiple references
+      #   result = client.images.remix(
+      #     prompt: "Create a scene with the dog from <img>1</img>, " \
+      #             "the background from <img>2</img>, and lighting from <img>3</img>",
+      #     reference_images: [dog_base64, background_base64, lighting_ref_base64]
+      #   )
+      #
+      # @see https://api.reve.com/console/docs#/Image/remix_v1_image_remix_post
+      def remix(prompt:, reference_images:, aspect_ratio: nil, version: nil)
+        validate_prompt!(prompt)
+        validate_reference_images!(reference_images)
+        validate_aspect_ratio!(aspect_ratio)
+
+        body = { prompt: prompt, reference_images: reference_images }
+        body[:aspect_ratio] = aspect_ratio if aspect_ratio
+        body[:version] = version if version
+
+        response = post(REMIX_ENDPOINT, body)
+        ImageResponse.new(status: response.status, headers: response.headers, body: response.body)
+      end
+    end
+  end
+end

data/lib/reve_ai/response.rb

@@ -0,0 +1,136 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # Base response wrapper for API responses.
+  #
+  # Provides access to HTTP status, headers, and parsed response body.
+  #
+  # @see ImageResponse
+  class Response
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [Hash] Response headers
+    attr_reader :headers
+
+    # @return [Hash] Parsed response body
+    attr_reader :body
+
+    # Creates a new response wrapper.
+    #
+    # @param status [Integer] HTTP status code
+    # @param headers [Hash] Response headers
+    # @param body [Hash] Parsed response body
+    def initialize(status:, headers:, body:)
+      @status = status
+      @headers = headers
+      @body = body
+    end
+
+    # Checks if the response indicates success (2xx status).
+    #
+    # @return [Boolean] true if status is between 200 and 299
+    def success?
+      status >= 200 && status < 300
+    end
+
+    # Returns the request ID for this response.
+    #
+    # Useful for debugging and support requests.
+    #
+    # @return [String, nil] Request ID from body or headers
+    def request_id
+      body[:request_id] || headers["x-reve-request-id"]
+    end
+  end
+
+  # Response wrapper for image generation API responses.
+  #
+  # Provides convenient accessors for image data, version info,
+  # content policy status, and credit usage.
+  #
+  # @example Accessing image data
+  #   result = client.images.create(prompt: "A sunset")
+  #   png_data = Base64.decode64(result.base64)
+  #   File.binwrite("image.png", png_data)
+  #
+  # @example Checking content policy
+  #   result = client.images.create(prompt: "...")
+  #   if result.content_violation?
+  #     puts "Content policy violated"
+  #   end
+  #
+  # @example Tracking credit usage
+  #   result = client.images.create(prompt: "A cat")
+  #   puts "Used #{result.credits_used} credits, #{result.credits_remaining} remaining"
+  #
+  # @see Response
+  class ImageResponse < Response
+    # Returns the base64 encoded image data.
+    #
+    # The image is in PNG format. Use Base64.decode64 to get raw bytes.
+    #
+    # @return [String, nil] Base64 encoded PNG image data
+    #
+    # @example Save to file
+    #   require "base64"
+    #   png_bytes = Base64.decode64(result.image)
+    #   File.binwrite("output.png", png_bytes)
+    def image
+      body[:image]
+    end
+
+    # Alias for {#image}.
+    #
+    # @return [String, nil] Base64 encoded PNG image data
+    # @see #image
+    def base64
+      image
+    end
+
+    # Returns the model version used for generation.
+    #
+    # @return [String, nil] Model version (e.g., "reve-create@20250915")
+    #
+    # @example
+    #   result.version # => "reve-create@20250915"
+    def version
+      body[:version] || headers["x-reve-version"]
+    end
+
+    # Checks if the generated image violates content policy.
+    #
+    # @return [Boolean] true if content policy was violated
+    #
+    # @example
+    #   if result.content_violation?
+    #     puts "Warning: Content policy violated"
+    #   end
+    def content_violation?
+      body[:content_violation] == true ||
+        headers["x-reve-content-violation"] == "true"
+    end
+
+    # Returns the number of credits used for this request.
+    #
+    # @return [Integer, nil] Credits consumed by this generation
+    #
+    # @example
+    #   puts "This request used #{result.credits_used} credits"
+    def credits_used
+      body[:credits_used] || headers["x-reve-credits-used"]&.to_i
+    end
+
+    # Returns the number of credits remaining after this request.
+    #
+    # @return [Integer, nil] Remaining credit balance
+    #
+    # @example
+    #   if result.credits_remaining < 100
+    #     puts "Warning: Low credit balance"
+    #   end
+    def credits_remaining
+      body[:credits_remaining] || headers["x-reve-credits-remaining"]&.to_i
+    end
+  end
+end

data/lib/reve_ai/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module ReveAI
+  # @return [String] Current gem version
+  VERSION = "0.1.0"
+end