fizzy-sdk 0.1.0

data/lib/fizzy/request_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Result information for completed HTTP requests.
+  RequestResult = Data.define(:status_code, :duration, :error, :retry_after, :from_cache) do
+    def initialize(status_code: nil, duration: 0.0, error: nil, retry_after: nil, from_cache: false)
+      super
+    end
+
+    def success?
+      status_code && status_code >= 200 && status_code < 300
+    end
+  end
+end

data/lib/fizzy/resilience.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Configuration container for resilience patterns.
+  #
+  # Bundles circuit breaker, bulkhead, and rate limiter settings
+  # into a single configuration object.
+  #
+  # @example
+  #   resilience = Fizzy::ResilienceConfig.new(
+  #     circuit_breaker: { threshold: 5, timeout: 30 },
+  #     bulkhead: { max_concurrent: 10, timeout: 5 },
+  #     rate_limiter: { rate: 10, burst: 20 }
+  #   )
+  class ResilienceConfig
+    # @return [CircuitBreaker, nil]
+    attr_reader :circuit_breaker
+
+    # @return [Bulkhead, nil]
+    attr_reader :bulkhead
+
+    # @return [RateLimiter, nil]
+    attr_reader :rate_limiter
+
+    # @param circuit_breaker [Hash, nil] CircuitBreaker options
+    # @param bulkhead [Hash, nil] Bulkhead options
+    # @param rate_limiter [Hash, nil] RateLimiter options
+    def initialize(circuit_breaker: nil, bulkhead: nil, rate_limiter: nil)
+      @circuit_breaker = circuit_breaker ? CircuitBreaker.new(**circuit_breaker) : nil
+      @bulkhead = bulkhead ? Bulkhead.new(**bulkhead) : nil
+      @rate_limiter = rate_limiter ? RateLimiter.new(**rate_limiter) : nil
+    end
+
+    # Wraps a block with all configured resilience patterns.
+    #
+    # Execution order: rate_limiter -> bulkhead -> circuit_breaker -> block
+    #
+    # @yield the operation to protect
+    # @return the result of the block
+    def call(&block)
+      block = wrap_with_circuit_breaker(block) if @circuit_breaker
+      block = wrap_with_bulkhead(block) if @bulkhead
+      @rate_limiter&.acquire
+      block.call
+    end
+
+    private
+
+    def wrap_with_circuit_breaker(block)
+      breaker = @circuit_breaker
+      -> { breaker.call(&block) }
+    end
+
+    def wrap_with_bulkhead(block)
+      bh = @bulkhead
+      -> { bh.call(&block) }
+    end
+  end
+end

data/lib/fizzy/security.rb

@@ -0,0 +1,103 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Fizzy
+  # Security helpers for URL validation, message truncation, and header redaction.
+  # Used across the SDK to enforce HTTPS, prevent SSRF, and protect sensitive data.
+  module Security
+    MAX_ERROR_MESSAGE_BYTES = 500
+    MAX_RESPONSE_BODY_BYTES = 50 * 1024 * 1024 # 50 MB
+    MAX_ERROR_BODY_BYTES = 1 * 1024 * 1024      # 1 MB
+
+    def self.truncate(str, max = MAX_ERROR_MESSAGE_BYTES)
+      return str if str.nil? || str.bytesize <= max
+
+      max <= 3 ? str.byteslice(0, max) : str.byteslice(0, max - 3) + "..."
+    end
+
+    def self.require_https!(url, label = "URL")
+      uri = URI.parse(url.to_s)
+      raise UsageError.new("#{label} must use HTTPS: #{url}") unless uri.scheme&.downcase == "https"
+    rescue URI::InvalidURIError
+      raise UsageError.new("Invalid #{label}: #{url}")
+    end
+
+    def self.same_origin?(a, b)
+      ua = URI.parse(a)
+      ub = URI.parse(b)
+      return false if ua.scheme.nil? || ub.scheme.nil?
+
+      ua.scheme.downcase == ub.scheme.downcase &&
+        normalize_host(ua) == normalize_host(ub)
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.resolve_url(base, target)
+      URI.join(base, target).to_s
+    rescue URI::InvalidURIError
+      target
+    end
+
+    def self.normalize_host(uri)
+      host = uri.host&.downcase
+      port = uri.port
+      return host if port.nil?
+      return host if uri.scheme&.downcase == "https" && port == 443
+      return host if uri.scheme&.downcase == "http" && port == 80
+
+      "#{host}:#{port}"
+    end
+
+    def self.check_body_size!(body, max, label = "Response")
+      return if body.nil?
+
+      if body.bytesize > max
+        raise Fizzy::APIError.new(
+          "#{label} body too large (#{body.bytesize} bytes, max #{max})"
+        )
+      end
+    end
+
+    def self.localhost?(url)
+      uri = URI.parse(url.to_s)
+      host = uri.host&.downcase
+      return false if host.nil?
+
+      host == "localhost" ||
+        host == "127.0.0.1" ||
+        host == "::1" ||
+        host == "[::1]" ||
+        host.end_with?(".localhost")
+    rescue URI::InvalidURIError
+      false
+    end
+
+    def self.require_https_unless_localhost!(url, label = "URL")
+      return if localhost?(url)
+
+      require_https!(url, label)
+    end
+
+    # Headers that contain sensitive values and should be redacted.
+    SENSITIVE_HEADERS = %w[
+      authorization
+      cookie
+      set-cookie
+      x-csrf-token
+    ].freeze
+
+    # Returns a copy of the headers with sensitive values replaced by "[REDACTED]".
+    #
+    # @param headers [Hash] the headers hash (case-insensitive keys)
+    # @return [Hash] a new hash with sensitive values redacted
+    def self.redact_headers(headers)
+      result = {}
+      headers.each do |key, value|
+        result[key] = SENSITIVE_HEADERS.include?(key.to_s.downcase) ? "[REDACTED]" : value
+      end
+      result
+    end
+  end
+end

data/lib/fizzy/services/base_service.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require_relative "../errors"
+
+module Fizzy
+  module Services
+    # Base service class for Fizzy API services.
+    #
+    # Provides shared functionality for all service classes including:
+    # - HTTP method delegation (http_get, http_post, etc.)
+    # - Pagination support
+    # - Operation hooks (with_operation, wrap_paginated)
+    #
+    # @example
+    #   class CardsService < BaseService
+    #     def list(board_id:)
+    #       paginate("/boards/#{board_id}/cards")
+    #     end
+    #   end
+    class BaseService
+      # @param client [Object] the parent client (Client)
+      def initialize(client)
+        @client = client
+        @hooks = client.hooks
+      end
+
+      protected
+
+      # Wraps a service operation with hooks for observability.
+      # @param service [String] service name (e.g., "boards")
+      # @param operation [String] operation name (e.g., "list")
+      # @param resource_type [String, nil] resource type (e.g., "Board")
+      # @param is_mutation [Boolean] whether this is a write operation
+      # @param resource_id [Integer, String, nil] resource ID
+      # @yield the operation to execute
+      # @return the result of the block
+      def with_operation(service:, operation:, resource_type: nil, is_mutation: false, resource_id: nil)
+        info = OperationInfo.new(
+          service: service, operation: operation, resource_type: resource_type,
+          is_mutation: is_mutation, resource_id: resource_id
+        )
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        safe_hook { @hooks.on_operation_start(info) }
+        result = yield
+        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        safe_hook { @hooks.on_operation_end(info, OperationResult.new(duration_ms: duration, error: nil)) }
+        result
+      rescue => e
+        duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+        safe_hook { @hooks.on_operation_end(info, OperationResult.new(duration_ms: duration, error: e)) }
+        raise
+      end
+
+      # Wraps a lazy Enumerator so operation hooks fire around actual iteration,
+      # not at enumerator creation time. Hooks fire when the consumer begins
+      # iterating (.each, .to_a, .first, etc.) and end fires via ensure when
+      # iteration completes, errors, or is cut short by break/take.
+      def wrap_paginated(service:, operation:, is_mutation: false, resource_id: nil)
+        info = OperationInfo.new(
+          service: service, operation: operation,
+          is_mutation: is_mutation, resource_id: resource_id
+        )
+        enum = yield
+
+        hooks = @hooks
+        Enumerator.new do |yielder|
+          start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          error = nil
+          begin
+            safe_hook { hooks.on_operation_start(info) }
+            enum.each { |item| yielder.yield(item) }
+          rescue => e
+            error = e
+            raise
+          ensure
+            duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+            safe_hook { hooks.on_operation_end(info, OperationResult.new(duration_ms: duration, error: error)) }
+          end
+        end
+      end
+
+      # Invoke a hook callback, swallowing exceptions so hooks never break SDK behavior.
+      def safe_hook
+        yield
+      rescue => e
+        warn "Fizzy hook error: #{e.class}: #{e.message}"
+      end
+
+      # @return [Http] the HTTP client for direct access
+      def http
+        @client.http
+      end
+
+      # Helper to remove nil values from a hash.
+      # @param hash [Hash] the input hash
+      # @return [Hash] hash with nil values removed
+      def compact_params(**kwargs)
+        kwargs.compact
+      end
+
+      # Delegate HTTP methods to the client with http_ prefix to avoid conflicts
+      # with service method names (e.g., service.get vs http_get)
+      %i[get post put patch delete post_raw].each do |method|
+        define_method(:"http_#{method}") do |*args, **kwargs, &block|
+          @client.public_send(method, *args, **kwargs, &block)
+        end
+      end
+
+      # Paginate doesn't conflict with service methods, keep as-is
+      def paginate(...)
+        @client.paginate(...)
+      end
+    end
+  end
+end

data/lib/fizzy/static_token_provider.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # A simple token provider that returns a static access token.
+  # Useful for testing or when you manage token refresh externally.
+  #
+  # @example
+  #   provider = Fizzy::StaticTokenProvider.new(ENV["FIZZY_ACCESS_TOKEN"])
+  class StaticTokenProvider
+    include TokenProvider
+
+    # @param token [String] the static access token
+    def initialize(token)
+      raise ArgumentError, "token cannot be nil or empty" if token.nil? || token.empty?
+
+      @token = token
+    end
+
+    # @return [String] the access token
+    def access_token
+      @token
+    end
+  end
+end

data/lib/fizzy/token_provider.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Fizzy
+  # Interface for providing access tokens.
+  # Implement this to provide custom token management.
+  #
+  # @example Static token provider
+  #   token_provider = Fizzy::StaticTokenProvider.new("your-access-token")
+  #   client = Fizzy::Client.new(config: config, token_provider: token_provider)
+  #
+  # @example Custom token provider with refresh
+  #   class MyTokenProvider
+  #     include Fizzy::TokenProvider
+  #
+  #     def access_token
+  #       # Return current token, refreshing if needed
+  #     end
+  #
+  #     def refresh
+  #       # Refresh the token
+  #     end
+  #   end
+  module TokenProvider
+    # Returns the current access token.
+    # @return [String] the access token
+    def access_token
+      raise NotImplementedError, "#{self.class} must implement #access_token"
+    end
+
+    # Refreshes the access token.
+    # @return [Boolean] true if refresh succeeded
+    def refresh
+      false
+    end
+
+    # Returns whether token refresh is supported.
+    # @return [Boolean]
+    def refreshable?
+      false
+    end
+  end
+end

data/lib/fizzy/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Fizzy
+  VERSION = "0.1.0"
+  API_VERSION = "2026-03-01"
+end

data/lib/fizzy/webhooks/verify.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Fizzy
+  module Webhooks
+    # HMAC-SHA256 signature verification for webhook payloads.
+    module Verify
+      # Verifies an HMAC-SHA256 signature for a webhook payload.
+      # Returns false if secret or signature is empty/nil.
+      def self.valid?(payload:, signature:, secret:)
+        return false if secret.nil? || secret.empty?
+        return false if signature.nil? || signature.empty?
+
+        expected = compute_signature(payload: payload, secret: secret)
+        secure_compare(expected, signature)
+      end
+
+      # Computes the HMAC-SHA256 signature for a webhook payload.
+      def self.compute_signature(payload:, secret:)
+        OpenSSL::HMAC.hexdigest("SHA256", secret, payload)
+      end
+
+      # Timing-safe string comparison
+      def self.secure_compare(a, b)
+        return false if a.nil? || b.nil?
+        return false if a.bytesize != b.bytesize
+
+        # Use OpenSSL's constant-time comparison via HMAC
+        OpenSSL.fixed_length_secure_compare(a, b)
+      end
+
+      private_class_method :secure_compare
+    end
+  end
+end

data/lib/fizzy.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+# Set up Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false)
+
+# Ignore hand-written services - we use generated services instead (spec-conformant)
+# EXCEPT: base_service.rb (infrastructure)
+loader.ignore("#{__dir__}/fizzy/services")
+
+# Collapse the generated directory so Fizzy::Generated::Services becomes Fizzy::Services
+loader.collapse("#{__dir__}/fizzy/generated")
+
+# Ignore errors.rb - it defines multiple classes, loaded explicitly below
+loader.ignore("#{__dir__}/fizzy/errors.rb")
+# Ignore auth_strategy.rb - defines both AuthStrategy and BearerAuth
+loader.ignore("#{__dir__}/fizzy/auth_strategy.rb")
+# Ignore operation_info.rb - defines both OperationInfo and OperationResult
+loader.ignore("#{__dir__}/fizzy/operation_info.rb")
+loader.setup
+
+# Load infrastructure that generated services depend on
+require_relative "fizzy/errors"
+require_relative "fizzy/auth_strategy"
+require_relative "fizzy/operation_info"
+require_relative "fizzy/services/base_service"
+
+# Load generated types if available
+begin
+  require_relative "fizzy/generated/types"
+rescue LoadError
+  # Generated types not available yet
+end
+
+# Main entry point for the Fizzy SDK.
+#
+# The SDK follows a Client pattern:
+# - Client: Holds shared resources (HTTP client, auth strategy, hooks)
+# - Provides service accessors for all 15 Fizzy services
+#
+# @example Basic usage
+#   client = Fizzy.client(access_token: ENV["FIZZY_ACCESS_TOKEN"])
+#   boards = client.boards.list.to_a
+#
+# @example With hooks for logging
+#   class MyHooks
+#     include Fizzy::Hooks
+#
+#     def on_request_start(info)
+#       puts "Starting #{info.method} #{info.url}"
+#     end
+#
+#     def on_request_end(info, result)
+#       puts "Completed in #{result.duration}s"
+#     end
+#   end
+#
+#   client = Fizzy.client(access_token: token, hooks: MyHooks.new)
+module Fizzy
+  # Creates a new Fizzy client.
+  #
+  # This is a convenience method that creates a Client with the given options.
+  #
+  # @param access_token [String, nil] API access token
+  # @param auth [AuthStrategy, nil] custom authentication strategy
+  # @param base_url [String] Base URL for API requests
+  # @param hooks [Hooks, nil] Observability hooks
+  # @return [Client]
+  #
+  # @example With access token
+  #   client = Fizzy.client(access_token: "abc123")
+  #   boards = client.boards.list.to_a
+  #
+  # @example With custom auth strategy
+  #   client = Fizzy.client(auth: Fizzy::CookieAuth.new("session_value"))
+  def self.client(
+    access_token: nil,
+    auth: nil,
+    base_url: Config::DEFAULT_BASE_URL,
+    hooks: nil
+  )
+    raise ArgumentError, "provide either access_token or auth, not both" if access_token && auth
+    raise ArgumentError, "provide access_token or auth" if !access_token && !auth
+
+    config = Config.new(base_url: base_url)
+
+    if auth
+      Client.new(config: config, auth_strategy: auth, hooks: hooks)
+    else
+      token_provider = StaticTokenProvider.new(access_token)
+      Client.new(config: config, token_provider: token_provider, hooks: hooks)
+    end
+  end
+end

data/scripts/generate-metadata.rb

@@ -0,0 +1,105 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Extracts x-fizzy-* extensions from OpenAPI spec into a runtime-accessible metadata file.
+# This allows the Ruby SDK to read operation metadata at runtime for retry, pagination, etc.
+#
+# Usage: ruby scripts/generate-metadata.rb > lib/fizzy/generated/metadata.json
+
+require 'json'
+require 'time'
+
+# Extract metadata from OpenAPI spec
+class MetadataExtractor
+  METHODS = %w[get post put patch delete].freeze
+
+  def initialize(openapi_path)
+    @openapi = JSON.parse(File.read(openapi_path))
+  end
+
+  def extract
+    operations = {}
+
+    (@openapi['paths'] || {}).each_value do |path_item|
+      METHODS.each do |method|
+        operation = path_item[method]
+        next unless operation
+
+        operation_id = operation['operationId']
+        next unless operation_id
+
+        metadata = extract_operation_metadata(operation)
+        operations[operation_id] = metadata if metadata.any?
+      end
+    end
+
+    {
+      '$schema' => 'https://fizzy.do/schemas/sdk-metadata.json',
+      'version' => '1.0.0',
+      'generated' => Time.now.utc.iso8601,
+      'operations' => operations
+    }
+  end
+
+  private
+
+  def extract_operation_metadata(operation)
+    metadata = {}
+
+    # Extract x-fizzy-retry
+    if (retry_config = operation['x-fizzy-retry'])
+      metadata['retry'] = {
+        'maxAttempts' => retry_config['maxAttempts'],
+        'baseDelayMs' => retry_config['baseDelayMs'],
+        'backoff' => retry_config['backoff'],
+        'retryOn' => retry_config['retryOn']
+      }
+    end
+
+    # Extract x-fizzy-pagination
+    if (pagination = operation['x-fizzy-pagination'])
+      metadata['pagination'] = {
+        'style' => pagination['style'],
+        'pageParam' => pagination['pageParam'],
+        'maxPageSize' => pagination['maxPageSize']
+      }.compact
+    end
+
+    # Extract x-fizzy-idempotent
+    if (idempotent = operation['x-fizzy-idempotent'])
+      metadata['idempotent'] = {
+        'keySupported' => idempotent['keySupported'],
+        'keyHeader' => idempotent['keyHeader'],
+        'natural' => idempotent['natural']
+      }.compact
+    end
+
+    # Extract x-fizzy-sensitive
+    if (sensitive = operation['x-fizzy-sensitive'])
+      metadata['sensitive'] = sensitive.map do |s|
+        {
+          'field' => s['field'],
+          'category' => s['category'],
+          'redact' => s['redact']
+        }.compact
+      end
+    end
+
+    metadata
+  end
+end
+
+# Main execution
+if __FILE__ == $PROGRAM_NAME
+  openapi_path = ARGV[0] || File.expand_path('../../openapi.json', __dir__)
+
+  unless File.exist?(openapi_path)
+    warn "Error: OpenAPI file not found: #{openapi_path}"
+    exit 1
+  end
+
+  extractor = MetadataExtractor.new(openapi_path)
+  metadata = extractor.extract
+
+  puts JSON.pretty_generate(metadata)
+end