fizzy-sdk 0.1.0

data/lib/fizzy/hooks.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Interface for observability hooks.
+  # Implement this to add logging, metrics, or tracing to HTTP requests.
+  #
+  # @example Custom hooks with logging
+  #   class LoggingHooks
+  #     include Fizzy::Hooks
+  #
+  #     def on_request_start(info)
+  #       puts "Starting #{info.method} #{info.url}"
+  #     end
+  #
+  #     def on_request_end(info, result)
+  #       puts "Completed #{info.method} #{info.url} - #{result.status_code} (#{result.duration}s)"
+  #     end
+  #   end
+  #
+  #   client = Fizzy::Client.new(config: config, token_provider: provider, hooks: LoggingHooks.new)
+  module Hooks
+    # Called when a service operation starts (e.g., boards.list, cards.create).
+    # @param info [OperationInfo] operation information
+    # @return [void]
+    def on_operation_start(info)
+      # Override in implementation
+    end
+
+    # Called when a service operation completes (success or failure).
+    # @param info [OperationInfo] operation information
+    # @param result [OperationResult] result information
+    # @return [void]
+    def on_operation_end(info, result)
+      # Override in implementation
+    end
+
+    # Called when an HTTP request starts.
+    # @param info [RequestInfo] request information
+    # @return [void]
+    def on_request_start(info)
+      # Override in implementation
+    end
+
+    # Called when an HTTP request completes (success or failure).
+    # @param info [RequestInfo] request information
+    # @param result [RequestResult] result information
+    # @return [void]
+    def on_request_end(info, result)
+      # Override in implementation
+    end
+
+    # Called when a request is retried.
+    # @param info [RequestInfo] request information
+    # @param attempt [Integer] the next attempt number
+    # @param error [Exception] the error that triggered the retry
+    # @param delay [Float] seconds until retry
+    # @return [void]
+    def on_retry(info, attempt, error, delay)
+      # Override in implementation
+    end
+
+    # Called when pagination fetches the next page.
+    # @param url [String] the next page URL
+    # @param page [Integer] the page number
+    # @return [void]
+    def on_paginate(url, page)
+      # Override in implementation
+    end
+  end
+end

data/lib/fizzy/http.rb

@@ -0,0 +1,411 @@
+# frozen_string_literal: true
+
+require "faraday"
+require "json"
+require "time"
+require "uri"
+
+module Fizzy
+  # HTTP client layer with retry, backoff, and caching support.
+  # This is an internal class used by Client; you typically don't use it directly.
+  class Http
+    # Default User-Agent header
+    USER_AGENT = "fizzy-sdk-ruby/#{VERSION} (api:#{API_VERSION})".freeze
+
+    # @param config [Config] configuration settings
+    # @param token_provider [TokenProvider, nil] token provider (deprecated, use auth_strategy)
+    # @param auth_strategy [AuthStrategy, nil] authentication strategy
+    # @param hooks [Hooks] observability hooks
+    def initialize(config:, token_provider: nil, auth_strategy: nil, hooks: nil)
+      @config = config
+      @auth_strategy = auth_strategy || BearerAuth.new(token_provider)
+      @token_provider = token_provider || (@auth_strategy.is_a?(BearerAuth) ? @auth_strategy.token_provider : nil)
+      @hooks = hooks || NoopHooks.new
+      @faraday = build_faraday_client
+    end
+
+    # @return [String] the configured base URL
+    def base_url
+      @config.base_url
+    end
+
+    # Performs a GET request.
+    # @param path [String] URL path
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get(path, params: {})
+      request(:get, path, params: params)
+    end
+
+    # Performs a GET request to an absolute URL.
+    # Used for endpoints not on the base API.
+    # @param url [String] absolute URL
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get_absolute(url, params: {})
+      request(:get, url, params: params)
+    end
+
+    # Performs a POST request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @param retryable [Boolean, nil] override retry behavior (true for idempotent POSTs)
+    # @return [Response]
+    def post(path, body: nil, retryable: nil)
+      request(:post, path, body: body, retryable: retryable)
+    end
+
+    # Performs a PUT request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def put(path, body: nil)
+      request(:put, path, body: body)
+    end
+
+    # Performs a PATCH request.
+    # @param path [String] URL path
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def patch(path, body: nil)
+      request(:patch, path, body: body)
+    end
+
+    # Performs a DELETE request.
+    # @param path [String] URL path
+    # @param retryable [Boolean, nil] override retry behavior
+    # @return [Response]
+    def delete(path, retryable: nil)
+      request(:delete, path, retryable: retryable)
+    end
+
+    # Performs a POST request with raw binary data.
+    # Used for file uploads.
+    # @param path [String] URL path
+    # @param body [String, IO] raw binary data
+    # @param content_type [String] MIME content type
+    # @return [Response]
+    def post_raw(path, body:, content_type:)
+      url = build_url(path)
+      single_request_raw(:post, url, body: body, content_type: content_type, attempt: 1)
+    end
+
+    # Fetches all pages of a paginated resource.
+    # @param path [String] initial URL path
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate(path, params: {}, &block)
+      return to_enum(:paginate, path, params: params) unless block
+
+      base_url = build_url(path)
+      url = base_url
+      page = 0
+
+      loop do
+        page += 1
+        break if page > @config.max_pages
+
+        @hooks.on_paginate(url, page)
+        response = get(url, params: page == 1 ? params : {})
+
+        Security.check_body_size!(response.body, Security::MAX_RESPONSE_BODY_BYTES)
+
+        begin
+          items = JSON.parse(response.body)
+        rescue JSON::ParserError => e
+          raise Fizzy::APIError.new(
+            "Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}"
+          )
+        end
+        items.each(&block)
+
+        next_url = parse_next_link(response.headers["Link"])
+        break if next_url.nil?
+
+        next_url = Security.resolve_url(url, next_url)
+
+        unless Security.same_origin?(next_url, base_url)
+          raise Fizzy::APIError.new(
+            "Cross-origin pagination link rejected; refusing to follow " \
+            "from #{Security.truncate(url.to_s)} to #{Security.truncate(next_url.to_s)}"
+          )
+        end
+
+        url = next_url
+      end
+    end
+
+    private
+
+    def build_faraday_client
+      Faraday.new(url: @config.base_url) do |f|
+        f.options.timeout = @config.timeout
+        f.options.open_timeout = 10
+        f.request :json
+        f.response :raise_error
+        f.adapter Faraday.default_adapter
+      end
+    end
+
+    def request(method, path, params: {}, body: nil, retryable: nil)
+      url = build_url(path)
+      should_retry = retryable.nil? ? (method != :post) : retryable
+
+      if should_retry
+        request_with_retry(method, url, params: params, body: body)
+      else
+        single_request(method, url, params: params, body: body, attempt: 1)
+      end
+    end
+
+    def request_with_retry(method, url, params: {}, body: nil)
+      attempt = 0
+      last_error = nil
+
+      loop do
+        attempt += 1
+        break if attempt > @config.max_retries
+
+        begin
+          return single_request(method, url, params: params, body: body, attempt: attempt)
+        rescue Fizzy::RateLimitError, Fizzy::NetworkError, Fizzy::APIError => e
+          raise e unless e.retryable?
+
+          last_error = e
+
+          # Don't sleep if this was the last attempt
+          break if attempt >= @config.max_retries
+
+          delay = calculate_delay(attempt, e.retry_after)
+
+          @hooks.on_retry(
+            RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt),
+            attempt + 1, e, delay
+          )
+          sleep(delay)
+        end
+      end
+
+      raise last_error || Fizzy::APIError.new("Request failed after #{@config.max_retries} retries")
+    end
+
+    def single_request(method, url, params:, body:, attempt:, retry_count: 0)
+      info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
+      @hooks.on_request_start(info)
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        response = @faraday.run_request(method, url, body, request_headers) do |req|
+          req.params.merge!(params) if params.any?
+        end
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        result = RequestResult.new(status_code: response.status, duration: duration)
+        @hooks.on_request_end(info, result)
+
+        Response.new(
+          body: response.body,
+          status: response.status,
+          headers: response.headers
+        )
+      rescue Faraday::ServerError, Faraday::ClientError => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = handle_error(e)
+        result = RequestResult.new(
+          status_code: e.response&.dig(:status),
+          duration: duration,
+          error: error,
+          retry_after: error.respond_to?(:retry_after) ? error.retry_after : nil
+        )
+        @hooks.on_request_end(info, result)
+
+        # After a successful token refresh on 401, retry the request once
+        if error.is_a?(Fizzy::AuthError) && error.http_status == 401 && retry_count < 1 && @token_refreshed
+          @token_refreshed = false
+          return single_request(method, url, params: params, body: body, attempt: attempt, retry_count: retry_count + 1)
+        end
+
+        raise error
+      rescue Faraday::Error => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = Fizzy::NetworkError.new("Connection failed", cause: e)
+        result = RequestResult.new(duration: duration, error: error)
+        @hooks.on_request_end(info, result)
+        raise error
+      end
+    end
+
+    def request_headers
+      headers = {
+        "User-Agent" => USER_AGENT,
+        "Accept" => "application/json"
+      }
+      @auth_strategy.authenticate(headers)
+      headers
+    end
+
+    def single_request_raw(method, url, body:, content_type:, attempt:)
+      info = RequestInfo.new(method: method.to_s.upcase, url: url, attempt: attempt)
+      @hooks.on_request_start(info)
+
+      start_time = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+      begin
+        headers = request_headers.merge("Content-Type" => content_type)
+        response = @faraday.run_request(method, url, body, headers)
+
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        result = RequestResult.new(status_code: response.status, duration: duration)
+        @hooks.on_request_end(info, result)
+
+        Response.new(
+          body: response.body,
+          status: response.status,
+          headers: response.headers
+        )
+      rescue Faraday::ServerError, Faraday::ClientError => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = handle_error(e)
+        result = RequestResult.new(
+          status_code: e.response&.dig(:status),
+          duration: duration,
+          error: error,
+          retry_after: error.respond_to?(:retry_after) ? error.retry_after : nil
+        )
+        @hooks.on_request_end(info, result)
+        raise error
+      rescue Faraday::Error => e
+        duration = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start_time
+        error = Fizzy::NetworkError.new("Connection failed", cause: e)
+        result = RequestResult.new(duration: duration, error: error)
+        @hooks.on_request_end(info, result)
+        raise error
+      end
+    end
+
+    def handle_error(error)
+      status = error.response&.dig(:status)
+      body = error.response&.dig(:body)
+      headers = error.response&.dig(:headers) || {}
+
+      retry_after = parse_retry_after(headers["Retry-After"] || headers["retry-after"])
+      request_id = headers["X-Request-Id"] || headers["x-request-id"]
+
+      err = case status
+      when 401
+        # Try token refresh; flag for caller to retry
+        @token_refreshed = @token_provider&.refreshable? && @token_provider.refresh
+        Fizzy::AuthError.new("Authentication failed")
+      when 403
+        Fizzy::ForbiddenError.new("Access denied")
+      when 404
+        Fizzy::NotFoundError.new("Resource", "unknown")
+      when 429
+        Fizzy::RateLimitError.new(retry_after: retry_after)
+      when 400, 422
+        message = Security.truncate(Fizzy.parse_error_message(body) || "Validation failed")
+        Fizzy::ValidationError.new(message, http_status: status)
+      when 500
+        Fizzy::APIError.new("Server error (500)", http_status: 500, retryable: true)
+      when 502, 503, 504
+        Fizzy::APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
+      else
+        message = Security.truncate(Fizzy.parse_error_message(body) || "Request failed (HTTP #{status})")
+        Fizzy::APIError.from_status(status || 0, message)
+      end
+
+      err.instance_variable_set(:@request_id, request_id) if request_id
+      err
+    end
+
+    def build_url(path)
+      if path.start_with?("https://")
+        return path
+      elsif path.start_with?("http://")
+        return path if Security.localhost?(path)
+        raise Fizzy::UsageError.new("URL must use HTTPS: #{path}")
+      end
+
+      path = "/#{path}" unless path.start_with?("/")
+      "#{@config.base_url}#{path}"
+    end
+
+    def calculate_delay(attempt, server_retry_after)
+      return server_retry_after if server_retry_after&.positive?
+
+      # Exponential backoff: base_delay * 2^(attempt-1) + jitter
+      base = @config.base_delay * (2**(attempt - 1))
+      jitter = rand * @config.max_jitter
+      base + jitter
+    end
+
+    def parse_retry_after(value)
+      return nil if value.nil? || value.empty?
+
+      # Try parsing as seconds (integer)
+      seconds = Integer(value, exception: false)
+      return seconds if seconds&.positive?
+
+      # Try parsing as HTTP-date
+      begin
+        date = Time.httpdate(value)
+        diff = (date - Time.now).to_i
+        return diff if diff.positive?
+      rescue ArgumentError
+        # Not a valid HTTP-date
+      end
+
+      nil
+    end
+
+    def parse_next_link(link_header)
+      return nil if link_header.nil? || link_header.empty?
+
+      link_header.split(",").each do |part|
+        part = part.strip
+        next unless part.include?('rel="next"')
+
+        start = part.index("<")
+        finish = part.index(">", start || 0)
+        return part[(start + 1)...finish] if start && finish
+      end
+
+      nil
+    end
+  end
+
+  # Wraps an HTTP response.
+  class Response
+    # @return [String] response body
+    attr_reader :body
+
+    # @return [Integer] HTTP status code
+    attr_reader :status
+
+    # @return [Hash] response headers
+    attr_reader :headers
+
+    def initialize(body:, status:, headers:)
+      @body = body
+      @status = status
+      @headers = headers
+    end
+
+    # Parses the response body as JSON.
+    # @return [Hash, Array]
+    def json
+      @json ||= begin
+        Security.check_body_size!(@body, Security::MAX_RESPONSE_BODY_BYTES)
+        JSON.parse(@body)
+      end
+    end
+
+    # Returns whether the response was successful (2xx).
+    # @return [Boolean]
+    def success?
+      status >= 200 && status < 300
+    end
+  end
+end

data/lib/fizzy/logger_hooks.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Hooks implementation that logs to Ruby's Logger.
+  #
+  # @example
+  #   require "logger"
+  #   logger = Logger.new($stdout)
+  #   hooks = Fizzy::LoggerHooks.new(logger)
+  #   client = Fizzy::Client.new(config: config, token_provider: provider, hooks: hooks)
+  class LoggerHooks
+    include Hooks
+
+    # @param logger [Logger] Ruby logger instance
+    # @param level [Symbol] log level (:debug, :info, :warn, :error)
+    def initialize(logger, level: :debug)
+      @logger = logger
+      @level = level
+    end
+
+    def on_request_start(info)
+      @logger.send(@level, "HTTP #{info.method} #{info.url} (attempt #{info.attempt})")
+    end
+
+    def on_request_end(info, result)
+      if result.error
+        @logger.send(@level, "HTTP #{info.method} #{info.url} failed: #{result.error.message}")
+      else
+        cache_info = result.from_cache ? " (cached)" : ""
+        @logger.send(@level, \
+                     "HTTP #{info.method} #{info.url} -> #{result.status_code}#{cache_info}" \
+                     " (#{format("%.3f", result.duration)}s)")
+      end
+    end
+
+    def on_retry(info, attempt, error, delay)
+      @logger.send(@level, \
+                   "Retrying #{info.method} #{info.url} (attempt #{attempt})" \
+                   " in #{format("%.2f", delay)}s: #{error.message}")
+    end
+
+    def on_paginate(url, page)
+      @logger.send(@level, "Fetching page #{page}: #{url}")
+    end
+  end
+end

data/lib/fizzy/magic_link_flow.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Orchestrates the passwordless magic link authentication flow.
+  #
+  # The flow works in two steps:
+  # 1. Call CreateSession with an email address - this sends a magic link email
+  # 2. Call RedeemMagicLink with the token from the magic link URL
+  #
+  # After redemption, the response contains a session token that can be used
+  # with CookieAuth or BearerAuth for subsequent requests.
+  #
+  # @example
+  #   flow = Fizzy::MagicLinkFlow.new(base_url: "https://fizzy.do")
+  #   flow.request_magic_link(email: "user@example.com")
+  #   # User clicks magic link in email, your app extracts the token
+  #   session = flow.redeem(token: "magic-link-token-from-url")
+  #   # Use session token for authenticated requests
+  #   client = Fizzy.client(auth: Fizzy::CookieAuth.new(session["session_token"]))
+  class MagicLinkFlow
+    # @param base_url [String] Fizzy API base URL
+    # @param hooks [Hooks, nil] observability hooks
+    def initialize(base_url: Config::DEFAULT_BASE_URL, hooks: nil)
+      @config = Config.new(base_url: base_url)
+      @hooks = hooks || NoopHooks.new
+      @http = Http.new(config: @config, auth_strategy: NullAuth.new, hooks: @hooks)
+    end
+
+    # Step 1: Request a magic link email.
+    #
+    # @param email [String] the user's email address
+    # @return [Hash] response from the API
+    def request_magic_link(email:)
+      response = @http.post("/sessions", body: { email: email })
+      response.json
+    end
+
+    # Step 2: Redeem a magic link token to get a session.
+    #
+    # @param token [String] the magic link token from the URL
+    # @return [Hash] response containing session_token and user info
+    def redeem(token:)
+      response = @http.post("/sessions/redeem", body: { token: token })
+      response.json
+    end
+
+    # Null authentication strategy for unauthenticated requests.
+    # @api private
+    class NullAuth
+      include AuthStrategy
+
+      def authenticate(headers)
+        # No authentication needed for magic link flow initiation
+      end
+    end
+  end
+end

data/lib/fizzy/noop_hooks.rb

@@ -0,0 +1,9 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # No-op implementation of Hooks.
+  # Used as the default when no hooks are configured.
+  class NoopHooks
+    include Hooks
+  end
+end

data/lib/fizzy/operation_info.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Information about a service operation for observability hooks.
+  OperationInfo = Data.define(:service, :operation, :resource_type, :is_mutation, :resource_id) do
+    def initialize(service:, operation:, resource_type: nil, is_mutation: false, resource_id: nil)
+      super
+    end
+  end
+
+  # Result information for completed service operations.
+  OperationResult = Data.define(:duration_ms, :error) do
+    def initialize(duration_ms: 0, error: nil)
+      super
+    end
+  end
+end

data/lib/fizzy/rate_limiter.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Token bucket rate limiter for client-side rate limiting.
+  #
+  # Prevents the client from exceeding a configurable request rate,
+  # avoiding 429 responses from the server.
+  #
+  # @example
+  #   limiter = Fizzy::RateLimiter.new(rate: 10, burst: 20)
+  #   limiter.acquire  # blocks until a token is available
+  class RateLimiter
+    # @param rate [Numeric] tokens per second (sustained rate)
+    # @param burst [Integer] maximum token bucket size (burst capacity)
+    def initialize(rate: 10, burst: 20)
+      @rate = rate.to_f
+      @burst = burst
+      @tokens = burst.to_f
+      @last_refill = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @mutex = Mutex.new
+    end
+
+    # Acquires a token, blocking if necessary until one is available.
+    #
+    # @return [void]
+    def acquire
+      loop do
+        wait_time = nil
+
+        @mutex.synchronize do
+          refill
+          if @tokens >= 1.0
+            @tokens -= 1.0
+            return
+          else
+            wait_time = (1.0 - @tokens) / @rate
+          end
+        end
+
+        sleep(wait_time) if wait_time&.positive?
+      end
+    end
+
+    # Attempts to acquire a token without blocking.
+    #
+    # @return [Boolean] true if a token was acquired
+    def try_acquire
+      @mutex.synchronize do
+        refill
+        if @tokens >= 1.0
+          @tokens -= 1.0
+          true
+        else
+          false
+        end
+      end
+    end
+
+    private
+
+    def refill
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      elapsed = now - @last_refill
+      @tokens = [ @tokens + elapsed * @rate, @burst.to_f ].min
+      @last_refill = now
+    end
+  end
+end

data/lib/fizzy/request_info.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Information about an HTTP request for observability hooks.
+  RequestInfo = Data.define(:method, :url, :attempt) do
+    def initialize(method:, url:, attempt: 1)
+      super
+    end
+  end
+end