wip-ruby 0.2.0

data/Rakefile

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList["test/**/*_test.rb"]
+  t.warning = false
+end
+
+namespace :test do
+  Rake::TestTask.new(:unit) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/unit/**/*_test.rb"]
+    t.warning = false
+  end
+
+  Rake::TestTask.new(:integration) do |t|
+    t.libs << "test"
+    t.libs << "lib"
+    t.test_files = FileList["test/integration/**/*_test.rb"]
+    t.warning = false
+  end
+end
+
+desc "Run tests with coverage report"
+task :coverage do
+  ENV["COVERAGE"] = "true"
+  Rake::Task[:test].invoke
+end
+
+desc "Record VCR cassettes (requires WIP_API_KEY)"
+task :record_cassettes do
+  unless ENV["WIP_API_KEY"]
+    abort "ERROR: WIP_API_KEY environment variable required"
+  end
+
+  ENV["VCR"] = "all"
+  ruby "test/support/cassette_recorder.rb"
+end
+
+task default: :test

data/lib/wip/client.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+require_relative "http_client"
+require_relative "resources/todos"
+require_relative "resources/users"
+require_relative "resources/projects"
+require_relative "resources/uploads"
+require_relative "resources/viewer"
+require_relative "resources/comments"
+require_relative "resources/reactions"
+
+module Wip
+  # Main client class for interacting with the WIP API
+  #
+  # @example Basic usage
+  #   Wip.configure do |config|
+  #     config.api_key = "your-api-key"
+  #   end
+  #
+  #   client = Wip::Client.new
+  #   client.viewer.me
+  #   client.todos.create(body: "Shipped new feature!")
+  #
+  # @example Working with comments and reactions
+  #   # Add a comment to a todo
+  #   client.comments.create(
+  #     commentable_type: "Todo",
+  #     commentable_id: "todo_123",
+  #     body: "Great work!"
+  #   )
+  #
+  #   # React to a todo
+  #   client.reactions.react_to_todo("todo_123")
+  class Client
+    # @return [Configuration] The configuration instance
+    attr_reader :config
+
+    # @return [HTTPClient] The HTTP client instance
+    attr_reader :http_client
+
+    # Initialize a new API client
+    # @param config [Configuration] The configuration instance
+    def initialize(config = Wip.configuration)
+      @config = config
+      @config.validate!
+      @http_client = HTTPClient.new(config)
+    end
+
+    # @return [Resources::Todos] The todos resource
+    def todos
+      @todos ||= Resources::Todos.new(http_client)
+    end
+
+    # @return [Resources::Users] The users resource
+    def users
+      @users ||= Resources::Users.new(http_client)
+    end
+
+    # @return [Resources::Projects] The projects resource
+    def projects
+      @projects ||= Resources::Projects.new(http_client)
+    end
+
+    # @return [Resources::Uploads] The uploads resource
+    def uploads
+      @uploads ||= Resources::Uploads.new(http_client)
+    end
+
+    # @return [Resources::Viewer] The viewer resource
+    def viewer
+      @viewer ||= Resources::Viewer.new(http_client)
+    end
+
+    # @return [Resources::Comments] The comments resource
+    def comments
+      @comments ||= Resources::Comments.new(http_client)
+    end
+
+    # @return [Resources::Reactions] The reactions resource
+    def reactions
+      @reactions ||= Resources::Reactions.new(http_client)
+    end
+  end
+end

data/lib/wip/configuration.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Wip
+  # Configuration class for the Wip API client
+  # @api private
+  class Configuration
+    # Default API endpoint
+    DEFAULT_BASE_URL = "https://api.wip.co"
+    # Default request timeout in seconds
+    DEFAULT_TIMEOUT = 10
+    # Default number of retries for failed requests
+    DEFAULT_MAX_RETRIES = 2
+    # Maximum allowed retries
+    MAX_RETRIES = 5
+    # Minimum allowed timeout value
+    MIN_TIMEOUT = 1
+    # Maximum allowed timeout value
+    MAX_TIMEOUT = 60
+
+    # @return [String] API key for authentication
+    attr_accessor :api_key
+
+    # @return [String] Base URL for API requests
+    attr_accessor :base_url
+
+    # @return [Integer] Request timeout in seconds (1-60)
+    attr_accessor :timeout
+
+    # @return [Integer] Number of retries for failed requests (0-5)
+    attr_accessor :max_retries
+
+    # @return [Logger, nil] Logger instance for debugging
+    attr_accessor :logger
+
+    def initialize
+      @base_url = DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @max_retries = DEFAULT_MAX_RETRIES
+      @logger = nil
+    end
+
+    # Validates the configuration
+    # @raise [Error::ConfigurationError] if configuration is invalid
+    def validate!
+      validate_api_key!
+      validate_base_url!
+      validate_timeout!
+      validate_max_retries!
+      validate_logger!
+    end
+
+    private
+
+    def validate_api_key!
+      return if api_key&.is_a?(String) && !api_key.strip.empty?
+
+      raise Error::ConfigurationError, "API key is required and must be a non-empty string"
+    end
+
+    def validate_base_url!
+      return if base_url&.is_a?(String) && !base_url.strip.empty?
+
+      raise Error::ConfigurationError, "Base URL is required and must be a non-empty string"
+    end
+
+    def validate_timeout!
+      return if timeout.is_a?(Integer) && timeout.between?(MIN_TIMEOUT, MAX_TIMEOUT)
+
+      raise Error::ConfigurationError,
+            "Timeout must be an integer between #{MIN_TIMEOUT} and #{MAX_TIMEOUT} seconds"
+    end
+
+    def validate_max_retries!
+      return if max_retries.is_a?(Integer) && max_retries.between?(0, MAX_RETRIES)
+
+      raise Error::ConfigurationError,
+            "Max retries must be an integer between 0 and #{MAX_RETRIES}"
+    end
+
+    def validate_logger!
+      return unless logger
+      return if logger.respond_to?(:debug) && logger.respond_to?(:info) &&
+                logger.respond_to?(:warn) && logger.respond_to?(:error)
+
+      raise Error::ConfigurationError,
+            "Logger must respond to :debug, :info, :warn, and :error"
+    end
+  end
+end

data/lib/wip/error.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+module Wip
+  # Base error class for all Wip errors
+  class Error < StandardError
+    # @return [String] The error message
+    attr_reader :message
+
+    # @return [Integer, nil] The HTTP status code (if applicable)
+    attr_reader :status_code
+
+    # @return [Hash, nil] The raw response data (if applicable)
+    attr_reader :response_data
+
+    def initialize(message = nil, status_code: nil, response_data: nil)
+      @message = message
+      @status_code = status_code
+      @response_data = response_data
+      super(message)
+    end
+
+    # Configuration related errors
+    class ConfigurationError < Error; end
+
+    # Network related errors
+    class NetworkError < Error; end
+    class TimeoutError < NetworkError; end
+    class ConnectionError < NetworkError; end
+
+    # API related errors
+    class APIError < Error; end
+    class NotFoundError < APIError; end
+    class UnauthorizedError < APIError; end
+    class ForbiddenError < APIError; end
+    class RateLimitError < APIError; end
+    class ValidationError < APIError; end
+    class ServerError < APIError; end
+
+    # Upload related errors
+    class UploadError < Error; end
+
+    # Maps HTTP status codes to error classes
+    # @api private
+    STATUS_CODE_TO_ERROR = {
+      400 => ValidationError,
+      401 => UnauthorizedError,
+      403 => ForbiddenError,
+      404 => NotFoundError,
+      422 => ValidationError,
+      429 => RateLimitError,
+      500 => ServerError,
+      502 => ServerError,
+      503 => ServerError,
+      504 => ServerError
+    }.freeze
+
+    # Creates an error from an HTTP response
+    # @param response [Hash] The HTTP response
+    # @return [Error] The appropriate error instance
+    # @api private
+    def self.from_response(response)
+      status = response[:status]
+      data = response[:body]
+
+      # Extract error message from response body
+      message = if data.is_a?(Hash)
+        data["error"] || data["message"] || "Unknown error"
+      else
+        data.to_s
+      end
+
+      error_class = STATUS_CODE_TO_ERROR[status] || APIError
+      error_class.new(message, status_code: status, response_data: data)
+    end
+  end
+end

data/lib/wip/http_client.rb

@@ -0,0 +1,221 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "faraday/retry"
+require "json"
+require_relative "version"
+
+module Wip
+  # HTTP client for making API requests
+  # @api private
+  class HTTPClient
+    # Response object wrapping the HTTP response
+    # @api private
+    class Response
+      # @return [Integer] The HTTP status code
+      attr_reader :status
+
+      # @return [Hash] The response headers
+      attr_reader :headers
+
+      # @return [Hash] The parsed response body
+      attr_reader :body
+
+      # Initialize a new response
+      # @param status [Integer] The HTTP status code
+      # @param headers [Hash] The response headers
+      # @param body [Hash] The parsed response body
+      def initialize(status:, headers:, body:)
+        @status = status
+        @headers = headers
+        @body = body
+      end
+
+      # Check if the response indicates a resource was created
+      # @return [Boolean] True if status is 201 Created
+      def created?
+        status == 201
+      end
+
+      # Extract the resource from the response based on status and endpoint conventions
+      # @param resource_key [Symbol, String] The expected resource key for 201 responses
+      # @return [Hash] The resource data
+      def extract_resource(resource_key = nil)
+        if created? && resource_key
+          body[resource_key.to_s] || body[resource_key.to_sym]
+        else
+          body
+        end
+      end
+    end
+
+    # Default middleware stack for the Faraday connection
+    # NOTE: Response middleware is processed in REVERSE order of definition
+    MIDDLEWARE = proc do |f|
+      # Encode request bodies as JSON
+      f.request :json
+
+      # Raise errors for non-2xx responses (defined before :json so it runs AFTER parsing)
+      f.response :raise_error
+
+      # Parse response bodies as JSON (runs before :raise_error in response processing)
+      f.response :json, content_type: /\bjson$/
+
+      # Retry failed requests with exponential backoff
+      f.request :retry, {
+        # Default retry configuration
+        max: config.max_retries,
+        interval: 0.05,              # 50ms
+        interval_randomness: 0.5,    # Randomize interval by +/- 50%
+        backoff_factor: 2,           # Exponential backoff
+
+        # Exceptions to retry (including default ones)
+        exceptions: Faraday::Retry::Middleware::DEFAULT_EXCEPTIONS + [
+          Errno::ETIMEDOUT,
+          Timeout::Error
+        ],
+
+        # Only retry idempotent methods (PATCH is idempotent per HTTP spec)
+        methods: %i[delete get head options patch put],
+
+        # Status codes that trigger a retry
+        retry_statuses: [408, 429, 500, 502, 503, 504],
+
+        # Callback for logging retries
+        # Signature: (retry_count, exception, env) in faraday-retry 2.x
+        retry_block: lambda { |*args|
+          # Silently handle retries - logging is optional
+          # Different faraday-retry versions have different signatures
+          begin
+            retry_count, exception, env = args
+            logger = env&.request&.context&.dig(:config)&.logger
+            return unless logger
+
+            logger.warn(
+              "[Wip] Retry #{retry_count} for #{env.method.upcase} #{env.url}: " \
+              "#{exception&.class&.name}"
+            )
+          rescue StandardError
+            # Ignore logging errors during retry - don't break the retry flow
+          end
+        }
+      }
+
+      # Add logging if configured
+      if f.options.context&.config&.logger
+        f.response :logger, f.options.context.config.logger, {
+          headers: true,
+          bodies: true,
+          log_level: :debug,
+          formatter: proc { |*args| "[Wip] #{args.last}" }
+        }
+      end
+
+      # Use Net::HTTP adapter (default and most compatible)
+      f.adapter Faraday.default_adapter
+    end
+
+    # @return [Configuration] The configuration instance
+    attr_reader :config
+
+    # Initialize a new HTTP client
+    # @param config [Configuration] The configuration instance
+    def initialize(config)
+      @config = config
+    end
+
+    # Make a GET request
+    # @param path [String] The path to request
+    # @param params [Hash] Query parameters
+    # @return [Response] The response wrapper
+    def get(path, params = {})
+      request(:get, path, params: params)
+    end
+
+    # Make a POST request
+    # @param path [String] The path to request
+    # @param body [Hash] The request body
+    # @return [Response] The response wrapper
+    def post(path, body = {})
+      request(:post, path, body: body)
+    end
+
+    # Make a PUT request
+    # @param path [String] The path to request
+    # @param body [Hash] The request body
+    # @return [Response] The response wrapper
+    def put(path, body = {})
+      request(:put, path, body: body)
+    end
+
+    # Make a PATCH request
+    # @param path [String] The path to request
+    # @param body [Hash] The request body
+    # @return [Response] The response wrapper
+    def patch(path, body = {})
+      request(:patch, path, body: body)
+    end
+
+    # Make a DELETE request
+    # @param path [String] The path to request
+    # @param params [Hash] Query parameters
+    # @return [Response] The response wrapper
+    def delete(path, params = {})
+      request(:delete, path, params: params)
+    end
+
+    private
+
+    # Make an HTTP request
+    # @param method [Symbol] The HTTP method
+    # @param path [String] The path to request
+    # @param params [Hash] Query parameters
+    # @param body [Hash] The request body
+    # @return [Response] The response wrapper
+    def request(method, path, params: {}, body: nil)
+      # Add API key to query parameters
+      params = params.merge(api_key: config.api_key)
+
+      response = connection.run_request(method, path, body, nil) do |req|
+        req.params.merge!(params) unless params.empty?
+        req.options.timeout = config.timeout
+        req.options.open_timeout = config.timeout
+      end
+
+      Response.new(
+        status: response.status,
+        headers: response.headers,
+        body: response.body
+      )
+    rescue Faraday::ConnectionFailed, Faraday::SSLError => e
+      raise Error::ConnectionError, "Connection failed: #{e.message}"
+    rescue Faraday::TimeoutError => e
+      raise Error::TimeoutError, "Request timed out: #{e.message}"
+    rescue Faraday::ClientError, Faraday::ServerError => e
+      if e.response
+        response_hash = {
+          status: e.response[:status],
+          body: e.response[:body]
+        }
+        raise Error.from_response(response_hash)
+      else
+        raise Error::NetworkError, "HTTP error: #{e.message}"
+      end
+    rescue Faraday::Error => e
+      raise Error::NetworkError, "Request failed: #{e.message}"
+    end
+
+    # Returns a Faraday connection instance
+    # @return [Faraday::Connection] The connection instance
+    def connection
+      @connection ||= Faraday.new(url: config.base_url) do |f|
+        # Add our middleware stack
+        instance_exec(f, &MIDDLEWARE)
+
+        # Set user agent
+        f.headers["User-Agent"] = "wip-ruby/#{Wip::VERSION} Faraday/#{Faraday::VERSION}"
+        f.options.context = { config: config }
+      end
+    end
+  end
+end

data/lib/wip/models/base.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+require "time"
+
+module Wip
+  module Models
+    # Base class for all API models
+    class Base
+      class << self
+        # Define an attribute with optional type coercion
+        # @param name [Symbol] The attribute name
+        # @param type [Class, nil] The type to coerce to
+        def attribute(name, type: nil)
+          attributes[name] = type
+
+          # Define getter
+          define_method(name) do
+            @attributes[name]
+          end
+
+          # Define predicate method for boolean attributes
+          if type == :boolean
+            define_method("#{name}?") do
+              !!@attributes[name]
+            end
+          end
+        end
+
+        # @return [Hash] Map of attribute names to their types
+        def attributes
+          @attributes ||= {}
+        end
+
+        # Create a new instance from a JSON response
+        # @param json [Hash] The JSON response
+        # @return [Base] The new instance
+        def from_json(json)
+          new(json)
+        end
+      end
+
+      # @return [Hash] The coerced attributes
+      attr_reader :attributes
+
+      # @return [Hash] The raw, uncoerced attributes from the API
+      attr_reader :raw_attributes
+
+      # Initialize a new model
+      # @param attributes [Hash] The model attributes
+      def initialize(attributes = {})
+        @raw_attributes = attributes.dup
+        @attributes = {}
+        update_attributes(attributes)
+      end
+
+      # Update the model's attributes
+      # @param attributes [Hash] The new attributes
+      # @return [void]
+      def update_attributes(attributes)
+        @raw_attributes.merge!(attributes)
+        self.class.attributes.each do |name, type|
+          str_key = name.to_s
+          sym_key = name.to_sym
+          # Use key? to properly handle false/nil values
+          has_key = attributes.key?(str_key) || attributes.key?(sym_key)
+          next unless has_key
+
+          value = attributes.key?(str_key) ? attributes[str_key] : attributes[sym_key]
+          # Store nil values explicitly to distinguish "not set" from "explicitly null"
+          @attributes[name] = value.nil? ? nil : coerce_value(value, type)
+        end
+      end
+
+      # Get a raw attribute value by key
+      # @param key [String, Symbol] The attribute key
+      # @return [Object, nil] The raw attribute value
+      def [](key)
+        raw_attributes[key.to_s] || raw_attributes[key.to_sym]
+      end
+
+      # Check if a raw attribute exists
+      # @param key [String, Symbol] The attribute key
+      # @return [Boolean] Whether the attribute exists
+      def attribute?(key)
+        raw_attributes.key?(key.to_s) || raw_attributes.key?(key.to_sym)
+      end
+
+      # Get all unknown attributes (those not defined via attribute)
+      # @return [Hash] The unknown attributes
+      def unknown_attributes
+        known_keys = self.class.attributes.keys.flat_map { |k| [k.to_s, k.to_sym] }
+        raw_attributes.reject { |k, _| known_keys.include?(k) }
+      end
+
+      # @return [String] A human-readable representation of the model showing all attributes and their values
+      def inspect
+        "#<#{self.class} " + self.class.attributes.keys.map { |attr| "#{attr}: #{public_send(attr).inspect}" }.join(", ") + ">"
+      end
+
+      private
+
+      # Coerce a value to the specified type
+      # @param value [Object] The value to coerce
+      # @param type [Class, nil] The type to coerce to
+      # @return [Object] The coerced value
+      # @raise [ArgumentError] If the value cannot be coerced to the specified type
+      def coerce_value(value, type)
+        case type
+        when :boolean
+          !!value
+        when :time
+          return value if value.is_a?(Time)
+          begin
+            Time.parse(value)
+          rescue ArgumentError, TypeError
+            raise ArgumentError, "Invalid time value: #{value.inspect}"
+          end
+        when :integer
+          coerce_integer(value)
+        when :float
+          coerce_float(value)
+        when :string
+          value.to_s
+        when Array
+          return [] unless value.is_a?(Array)
+
+          value.map { |v| coerce_value(v, type.first) }
+        when Class
+          value.is_a?(type) ? value : type.from_json(value)
+        else
+          value
+        end
+      end
+
+      # Coerce a value to an integer with strict validation
+      # @param value [Object] The value to coerce
+      # @return [Integer] The coerced integer
+      # @raise [ArgumentError] If the value is not a valid integer
+      def coerce_integer(value)
+        return value if value.is_a?(Integer)
+        return value.to_i if value.is_a?(Float)
+        return value.to_i if value.is_a?(String) && value.match?(/\A-?\d+\z/)
+
+        raise ArgumentError, "Invalid integer value: #{value.inspect}"
+      end
+
+      # Coerce a value to a float with strict validation
+      # @param value [Object] The value to coerce
+      # @return [Float] The coerced float
+      # @raise [ArgumentError] If the value is not a valid float
+      def coerce_float(value)
+        return value.to_f if value.is_a?(Integer)
+        return value if value.is_a?(Float)
+        return value.to_f if value.is_a?(String) && value.match?(/\A-?\d+(\.\d+)?\z/)
+
+        raise ArgumentError, "Invalid float value: #{value.inspect}"
+      end
+    end
+  end
+end