fizzy-api-client 0.1.0

data/lib/fizzy_api_client/client.rb

@@ -0,0 +1,125 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  class Client
+    include Resources::Identity
+    include Resources::Boards
+    include Resources::Cards
+    include Resources::Columns
+    include Resources::Comments
+    include Resources::Steps
+    include Resources::Reactions
+    include Resources::Tags
+    include Resources::Users
+    include Resources::Notifications
+    include Resources::DirectUploads
+
+    attr_accessor :api_token, :base_url, :timeout, :open_timeout, :user_agent, :logger
+    attr_reader :account_slug
+
+    def initialize(api_token: nil, account_slug: nil, base_url: nil, timeout: nil,
+                   open_timeout: nil, user_agent: nil, logger: nil)
+      config = FizzyApiClient.configuration
+
+      @api_token = api_token || config.api_token
+      @base_url = base_url || config.base_url
+      @timeout = timeout || config.timeout
+      @open_timeout = open_timeout || config.open_timeout
+      @user_agent = user_agent || config.user_agent
+      @logger = logger || config.logger
+      self.account_slug = account_slug || config.account_slug
+    end
+
+    def account_slug=(value)
+      @account_slug = normalize_slug(value)
+    end
+
+    private
+
+    def connection
+      @connection ||= Connection.new(client_config)
+    end
+
+    def reset_connection!
+      @connection = nil
+    end
+
+    def client_config
+      OpenStruct.new(
+        api_token: api_token,
+        base_url: base_url,
+        timeout: timeout,
+        open_timeout: open_timeout,
+        user_agent: user_agent,
+        logger: logger
+      )
+    end
+
+    def effective_account_slug(override = nil)
+      slug = override || account_slug
+      raise ConfigurationError, "account_slug is required" unless slug
+
+      slug
+    end
+
+    def normalize_slug(slug)
+      return nil if slug.nil?
+
+      slug.to_s.sub(%r{^/}, "")
+    end
+
+    def paginate(path, params: {}, account_slug: nil, auto_paginate: false, page: nil)
+      slug = effective_account_slug(account_slug)
+      full_path = "/#{slug}#{path}"
+
+      params = params.merge(page: page) if page
+
+      response = connection.get(full_path, params: params)
+
+      return nil if response.no_content?
+
+      if auto_paginate
+        fetch_all_pages(response, params)
+      else
+        response.body
+      end
+    end
+
+    def fetch_all_pages(initial_response, _params)
+      results = initial_response.body || []
+      paginated = PaginatedResponse.new(
+        status: initial_response.status,
+        headers: initial_response.headers,
+        raw_body: initial_response.raw_body
+      )
+
+      while paginated.next_page?
+        next_url = paginated.next_page_url
+        uri = URI.parse(next_url)
+        response = connection.get(uri.path, params: parse_query(uri.query))
+        results.concat(response.body) if response.body.is_a?(Array)
+
+        paginated = PaginatedResponse.new(
+          status: response.status,
+          headers: response.headers,
+          raw_body: response.raw_body
+        )
+      end
+
+      results
+    end
+
+    def parse_query(query_string)
+      return {} unless query_string
+
+      params = {}
+      query_string.split("&").each do |pair|
+        key, value = pair.split("=")
+        key = URI.decode_www_form_component(key)
+        value = URI.decode_www_form_component(value) if value
+        params[key] = value
+      end
+      params
+    end
+  end
+end

data/lib/fizzy_api_client/colors.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  # Color mappings for column colors.
+  #
+  # Provides friendly named colors that map to the underlying CSS variable values
+  # expected by the Fizzy API.
+  #
+  # @example Using named colors
+  #   client.create_column(board_id: 'board_1', name: 'Review', color: :blue)
+  #   client.update_column('board_id', 'col_id', color: :lime)
+  #
+  # @example Using CSS variable directly (still supported)
+  #   client.create_column(board_id: 'board_1', name: 'Review', color: 'var(--color-card-4)')
+  #
+  module Colors
+    # Color name to CSS variable mapping
+    MAPPING = {
+      blue: "var(--color-card-default)",
+      gray: "var(--color-card-1)",
+      tan: "var(--color-card-2)",
+      yellow: "var(--color-card-3)",
+      lime: "var(--color-card-4)",
+      aqua: "var(--color-card-5)",
+      violet: "var(--color-card-6)",
+      purple: "var(--color-card-7)",
+      pink: "var(--color-card-8)"
+    }.freeze
+
+    # All available color names
+    NAMES = MAPPING.keys.freeze
+
+    # Individual color constants for convenience
+    BLUE = MAPPING[:blue]
+    GRAY = MAPPING[:gray]
+    TAN = MAPPING[:tan]
+    YELLOW = MAPPING[:yellow]
+    LIME = MAPPING[:lime]
+    AQUA = MAPPING[:aqua]
+    VIOLET = MAPPING[:violet]
+    PURPLE = MAPPING[:purple]
+    PINK = MAPPING[:pink]
+
+    class << self
+      # Resolves a color value to its CSS variable representation.
+      #
+      # Accepts:
+      # - Symbol color names (:blue, :lime, etc.)
+      # - String color names ("blue", "lime", etc.)
+      # - CSS variable strings (passed through unchanged)
+      # - nil (returns nil)
+      #
+      # @param color [Symbol, String, nil] the color to resolve
+      # @return [String, nil] the CSS variable value or nil
+      # @raise [ArgumentError] if the color name is not recognized
+      #
+      # @example
+      #   Colors.resolve(:blue)        #=> "var(--color-card-default)"
+      #   Colors.resolve("lime")       #=> "var(--color-card-4)"
+      #   Colors.resolve("var(--color-card-3)")  #=> "var(--color-card-3)"
+      #   Colors.resolve(nil)          #=> nil
+      #
+      def resolve(color)
+        return nil if color.nil?
+
+        # If it's already a CSS variable, pass through unchanged
+        return color.to_s if color.to_s.start_with?("var(")
+
+        # Convert to symbol for lookup
+        color_sym = color.to_s.downcase.to_sym
+
+        unless MAPPING.key?(color_sym)
+          raise ArgumentError, "Unknown color: #{color.inspect}. Valid colors: #{NAMES.join(', ')}"
+        end
+
+        MAPPING[color_sym]
+      end
+
+      # Checks if a color name is valid.
+      #
+      # @param color [Symbol, String] the color name to check
+      # @return [Boolean] true if valid
+      #
+      def valid?(color)
+        return true if color.to_s.start_with?("var(")
+
+        MAPPING.key?(color.to_s.downcase.to_sym)
+      end
+    end
+  end
+end

data/lib/fizzy_api_client/configuration.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  class Configuration
+    DEFAULT_BASE_URL = "https://app.fizzy.do"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_OPEN_TIMEOUT = 10
+
+    attr_reader :account_slug
+    attr_accessor :api_token, :base_url, :timeout, :open_timeout, :user_agent, :logger
+
+    def initialize
+      @api_token = ENV["FIZZY_API_TOKEN"]
+      @base_url = ENV["FIZZY_BASE_URL"] || DEFAULT_BASE_URL
+      @timeout = DEFAULT_TIMEOUT
+      @open_timeout = DEFAULT_OPEN_TIMEOUT
+      @user_agent = "FizzyApiClient/#{VERSION}"
+      @logger = nil
+      self.account_slug = ENV["FIZZY_ACCOUNT"]
+    end
+
+    def account_slug=(value)
+      @account_slug = normalize_slug(value)
+    end
+
+    private
+
+    def normalize_slug(slug)
+      return nil if slug.nil?
+
+      slug.to_s.sub(%r{^/}, "")
+    end
+  end
+end

data/lib/fizzy_api_client/connection.rb

@@ -0,0 +1,215 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  class Connection
+    def initialize(config)
+      @config = config
+    end
+
+    def get(path, params: {}, headers: {})
+      request(:get, path, params: params, headers: headers)
+    end
+
+    def post(path, body: {}, headers: {})
+      request(:post, path, body: body, headers: headers)
+    end
+
+    def put(path, body: {}, headers: {})
+      request(:put, path, body: body, headers: headers)
+    end
+
+    def patch(path, body: {}, headers: {})
+      request(:patch, path, body: body, headers: headers)
+    end
+
+    def delete(path, params: {}, headers: {})
+      request(:delete, path, params: params, headers: headers)
+    end
+
+    # Follow a Location header and return the resource
+    def follow_location(response)
+      return response unless response.created_with_location?
+
+      location = response.location
+      # Strip .json suffix if present for cleaner path
+      path = location.sub(/\.json\z/, "")
+      get(path)
+    end
+
+    def post_multipart(path, fields: {}, files: {}, headers: {})
+      request_multipart(:post, path, fields: fields, files: files, headers: headers)
+    end
+
+    def put_multipart(path, fields: {}, files: {}, headers: {})
+      request_multipart(:put, path, fields: fields, files: files, headers: headers)
+    end
+
+    private
+
+    def request(method, path, params: {}, body: {}, headers: {})
+      uri = build_uri(path, params)
+      http = build_http(uri)
+      req = build_request(method, uri, body, headers)
+
+      log_request(method, uri)
+      start_time = Time.now
+
+      begin
+        http_response = http.request(req)
+        elapsed_ms = ((Time.now - start_time) * 1000).round
+
+        response = build_response(http_response)
+        log_response(response.status, uri, elapsed_ms)
+
+        handle_errors(response, method, path)
+        response
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        log_error(e)
+        raise TimeoutError, "Request timed out: #{e.message}"
+      rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        log_error(e)
+        raise ConnectionError, "Connection failed: #{e.message}"
+      end
+    end
+
+    def request_multipart(method, path, fields:, files:, headers:)
+      uri = build_uri(path, {})
+      http = build_http(uri)
+
+      body, content_type = Multipart.build(fields, files)
+
+      req = build_multipart_request(method, uri, body, content_type, headers)
+
+      log_request(method, uri)
+      start_time = Time.now
+
+      begin
+        http_response = http.request(req)
+        elapsed_ms = ((Time.now - start_time) * 1000).round
+
+        response = build_response(http_response)
+        log_response(response.status, uri, elapsed_ms)
+
+        handle_errors(response, method, path)
+        response
+      rescue Net::OpenTimeout, Net::ReadTimeout => e
+        log_error(e)
+        raise TimeoutError, "Request timed out: #{e.message}"
+      rescue SocketError, Errno::ECONNREFUSED, Errno::ECONNRESET => e
+        log_error(e)
+        raise ConnectionError, "Connection failed: #{e.message}"
+      end
+    end
+
+    def build_uri(path, params)
+      base = URI.parse(@config.base_url)
+      request = Request.new(path: path, params: params)
+
+      URI.parse("#{base.scheme}://#{base.host}:#{base.port}#{request.full_path}")
+    end
+
+    def build_http(uri)
+      http = Net::HTTP.new(uri.host, uri.port)
+      http.use_ssl = uri.scheme == "https"
+      http.open_timeout = @config.open_timeout
+      http.read_timeout = @config.timeout
+      http
+    end
+
+    def build_request(method, uri, body, headers)
+      req = case method
+            when :get    then Net::HTTP::Get.new(uri.request_uri)
+            when :post   then Net::HTTP::Post.new(uri.request_uri)
+            when :put    then Net::HTTP::Put.new(uri.request_uri)
+            when :patch  then Net::HTTP::Patch.new(uri.request_uri)
+            when :delete then Net::HTTP::Delete.new(uri.request_uri)
+            end
+
+      apply_default_headers(req)
+      apply_custom_headers(req, headers)
+
+      if %i[post put patch].include?(method) && !body.empty?
+        req.body = body.to_json
+      end
+
+      req
+    end
+
+    def build_multipart_request(method, uri, body, content_type, headers)
+      req = case method
+            when :post then Net::HTTP::Post.new(uri.request_uri)
+            when :put  then Net::HTTP::Put.new(uri.request_uri)
+            end
+
+      apply_default_headers(req, skip_content_type: true)
+      apply_custom_headers(req, headers)
+      req["Content-Type"] = content_type
+      req.body = body
+
+      req
+    end
+
+    def apply_default_headers(req, skip_content_type: false)
+      req["Accept"] = "application/json"
+      req["Content-Type"] = "application/json" unless skip_content_type
+      req["User-Agent"] = @config.user_agent
+      req["Authorization"] = "Bearer #{@config.api_token}" if @config.api_token
+    end
+
+    def apply_custom_headers(req, headers)
+      headers.each { |key, value| req[key] = value }
+    end
+
+    def build_response(http_response)
+      headers = {}
+      http_response.each_header { |key, value| headers[key] = value }
+
+      Response.new(
+        status: http_response.code.to_i,
+        headers: headers,
+        raw_body: http_response.body
+      )
+    end
+
+    def handle_errors(response, method, path)
+      return if response.success? || response.not_modified?
+
+      error_class = error_class_for_status(response.status)
+      raise error_class.new(
+        status: response.status,
+        body: response.body,
+        method: method,
+        path: path
+      )
+    end
+
+    def error_class_for_status(status)
+      case status
+      when 401 then AuthenticationError
+      when 403 then ForbiddenError
+      when 404 then NotFoundError
+      when 422 then ValidationError
+      when 500..599 then ServerError
+      else ApiError
+      end
+    end
+
+    def log_request(method, uri)
+      return unless @config.logger
+
+      @config.logger.debug("[FizzyApiClient] #{method.to_s.upcase} #{uri}")
+    end
+
+    def log_response(status, uri, elapsed_ms)
+      return unless @config.logger
+
+      @config.logger.debug("[FizzyApiClient] #{status} #{uri} (#{elapsed_ms}ms)")
+    end
+
+    def log_error(error)
+      return unless @config.logger
+
+      @config.logger.error("[FizzyApiClient] #{error.class}: #{error.message}")
+    end
+  end
+end

data/lib/fizzy_api_client/error.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  # Base error class
+  class Error < StandardError; end
+
+  # Configuration errors (missing config)
+  class ConfigurationError < Error; end
+
+  # Network failures
+  class ConnectionError < Error; end
+
+  # Request timeout
+  class TimeoutError < Error; end
+
+  # API returned an error response
+  class ApiError < Error
+    attr_reader :status, :body, :method, :path
+
+    def initialize(message: nil, status: nil, body: nil, method: nil, path: nil)
+      @status = status
+      @body = body
+      @method = method
+      @path = path
+
+      error_message = build_message(message)
+      super(error_message)
+    end
+
+    private
+
+    def build_message(message)
+      parts = []
+      parts << message if message
+      parts << "Status: #{status}" if status
+      parts << extract_api_error_message if body.is_a?(Hash)
+      parts.join(" - ")
+    end
+
+    def extract_api_error_message
+      body[:error] || body["error"] || body[:errors] || body["errors"]
+    end
+  end
+
+  # 401 Unauthorized
+  class AuthenticationError < ApiError; end
+
+  # 403 Forbidden
+  class ForbiddenError < ApiError; end
+
+  # 404 Not Found
+  class NotFoundError < ApiError; end
+
+  # 422 Unprocessable Entity
+  class ValidationError < ApiError; end
+
+  # 500+ Server errors
+  class ServerError < ApiError; end
+end

data/lib/fizzy_api_client/multipart.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  module Multipart
+    class << self
+      def build(fields, files = {})
+        boundary = generate_boundary
+        body = build_body(fields, files, boundary)
+        content_type = "multipart/form-data; boundary=#{boundary}"
+
+        [body, content_type]
+      end
+
+      private
+
+      def generate_boundary
+        "----FizzyApiClient#{SecureRandom.hex(16)}"
+      end
+
+      def build_body(fields, files, boundary)
+        parts = []
+
+        # Add regular fields
+        fields.each do |key, value|
+          parts << field_part(key, value, boundary)
+        end
+
+        # Add file fields
+        files.each do |key, file_info|
+          parts << file_part(key, file_info, boundary)
+        end
+
+        # Close with final boundary
+        parts << "--#{boundary}--\r\n"
+
+        parts.join
+      end
+
+      def field_part(key, value, boundary)
+        "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{key}\"\r\n" \
+        "\r\n" \
+        "#{value}\r\n"
+      end
+
+      def file_part(key, file_info, boundary)
+        filename = file_info[:filename]
+        content_type = file_info[:content_type] || "application/octet-stream"
+        content = file_info[:content]
+
+        "--#{boundary}\r\n" \
+        "Content-Disposition: form-data; name=\"#{key}\"; filename=\"#{filename}\"\r\n" \
+        "Content-Type: #{content_type}\r\n" \
+        "\r\n" \
+        "#{content}\r\n"
+      end
+    end
+  end
+end

data/lib/fizzy_api_client/pagination.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  class PaginatedResponse < Response
+    def next_page?
+      !next_page_url.nil?
+    end
+  end
+end

data/lib/fizzy_api_client/request.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  class Request
+    attr_reader :path, :params, :path_params
+
+    def initialize(path:, params: {}, path_params: {})
+      @path = interpolate_path(path, path_params)
+      @params = params
+      @path_params = path_params
+    end
+
+    def full_path
+      return path if params.empty?
+
+      query_string = build_query_string(params)
+      "#{path}?#{query_string}"
+    end
+
+    def wrap_payload(resource_name, data)
+      { resource_name => data }
+    end
+
+    private
+
+    def interpolate_path(path, path_params)
+      result = path.dup
+      path_params.each do |key, value|
+        result.gsub!(":#{key}", value.to_s)
+      end
+      result
+    end
+
+    def build_query_string(params)
+      parts = []
+
+      params.each do |key, value|
+        if value.is_a?(Array)
+          value.each do |v|
+            parts << "#{key}[]=#{URI.encode_www_form_component(v.to_s)}"
+          end
+        else
+          parts << "#{key}=#{URI.encode_www_form_component(value.to_s)}"
+        end
+      end
+
+      parts.join("&")
+    end
+  end
+end

data/lib/fizzy_api_client/resources/boards.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module FizzyApiClient
+  module Resources
+    module Boards
+      def boards(page: nil, auto_paginate: false, account_slug: nil)
+        paginate("/boards", account_slug: account_slug, auto_paginate: auto_paginate, page: page)
+      end
+
+      def board(board_id, account_slug: nil)
+        slug = effective_account_slug(account_slug)
+        response = connection.get("/#{slug}/boards/#{board_id}")
+        response.body
+      end
+
+      def create_board(name:, all_access: nil, auto_postpone_period: nil, public_description: nil, account_slug: nil)
+        slug = effective_account_slug(account_slug)
+
+        payload = { name: name }
+        payload[:all_access] = all_access unless all_access.nil?
+        payload[:auto_postpone_period] = auto_postpone_period unless auto_postpone_period.nil?
+        payload[:public_description] = public_description unless public_description.nil?
+
+        response = connection.post("/#{slug}/boards", body: { board: payload })
+        response = connection.follow_location(response)
+        response.body
+      end
+
+      def update_board(board_id, name: nil, all_access: nil, auto_postpone_period: nil,
+                       public_description: nil, user_ids: nil, account_slug: nil)
+        slug = effective_account_slug(account_slug)
+
+        payload = {}
+        payload[:name] = name unless name.nil?
+        payload[:all_access] = all_access unless all_access.nil?
+        payload[:auto_postpone_period] = auto_postpone_period unless auto_postpone_period.nil?
+        payload[:public_description] = public_description unless public_description.nil?
+        payload[:user_ids] = user_ids unless user_ids.nil?
+
+        response = connection.put("/#{slug}/boards/#{board_id}", body: { board: payload })
+        response.no_content? ? nil : response.body
+      end
+
+      def delete_board(board_id, account_slug: nil)
+        slug = effective_account_slug(account_slug)
+        response = connection.delete("/#{slug}/boards/#{board_id}")
+        response.no_content? ? nil : response.body
+      end
+    end
+  end
+end