basecamp-sdk 0.2.1

data/lib/basecamp/webhooks/rack_middleware.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require_relative "receiver"
+
+module Basecamp
+  module Webhooks
+    # Rack middleware that intercepts POST requests to a configurable path
+    # and dispatches them to a WebhookReceiver for processing.
+    class RackMiddleware
+      DEFAULT_PATH = "/webhooks/basecamp"
+
+      def initialize(app, receiver:, path: DEFAULT_PATH)
+        @app = app
+        @receiver = receiver
+        @path = path
+      end
+
+      def call(env)
+        unless env["PATH_INFO"] == @path
+          return @app.call(env)
+        end
+
+        unless env["REQUEST_METHOD"] == "POST"
+          return [ 405, { "Content-Type" => "text/plain" }, [ "Method Not Allowed" ] ]
+        end
+
+        body = env["rack.input"].read
+        env["rack.input"].rewind
+
+        headers = lambda { |name|
+          # Rack normalizes headers to HTTP_UPPER_CASE format
+          rack_key = "HTTP_#{name.upcase.tr('-', '_')}"
+          env[rack_key]
+        }
+
+        begin
+          @receiver.handle_request(raw_body: body, headers: headers)
+          [ 200, { "Content-Type" => "text/plain" }, [ "OK" ] ]
+        rescue VerificationError
+          [ 401, { "Content-Type" => "text/plain" }, [ "Unauthorized" ] ]
+        rescue JSON::ParserError
+          [ 400, { "Content-Type" => "text/plain" }, [ "Bad Request" ] ]
+        rescue StandardError
+          [ 500, { "Content-Type" => "text/plain" }, [ "Internal Server Error" ] ]
+        end
+      end
+    end
+  end
+end

data/lib/basecamp/webhooks/receiver.rb

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "event"
+require_relative "verify"
+
+module Basecamp
+  module Webhooks
+    class VerificationError < StandardError; end
+
+    # Receives and routes webhook events from Basecamp.
+    # Framework-agnostic: works with raw body strings and a header accessor.
+    class Receiver
+      DEFAULT_SIGNATURE_HEADER = "X-Basecamp-Signature"
+      DEFAULT_DEDUP_WINDOW_SIZE = 1000
+
+      def initialize(secret: nil, signature_header: DEFAULT_SIGNATURE_HEADER, dedup_window_size: DEFAULT_DEDUP_WINDOW_SIZE)
+        @secret = secret
+        @signature_header = signature_header
+        @dedup_window_size = dedup_window_size
+        @handlers = {}
+        @any_handlers = []
+        @middleware = []
+        @dedup_seen = {}
+        @dedup_pending = {}
+        @dedup_order = []
+        @mutex = Mutex.new
+      end
+
+      # Register a handler for a specific event kind pattern.
+      # Supports glob patterns: "todo_*" matches "todo_created", etc.
+      def on(pattern, &handler)
+        @handlers[pattern] ||= []
+        @handlers[pattern] << handler
+        self
+      end
+
+      # Register a handler for all events.
+      def on_any(&handler)
+        @any_handlers << handler
+        self
+      end
+
+      # Add middleware to the processing chain.
+      # Middleware receives (event, next_proc) and must call next_proc.call to continue.
+      def use(&middleware)
+        @middleware << middleware
+        self
+      end
+
+      # Process a raw webhook request.
+      # Returns the parsed Event.
+      # Raises VerificationError if signature is invalid.
+      def handle_request(raw_body:, headers:)
+        # Verify signature
+        if @secret && !@secret.empty?
+          signature = extract_header(headers, @signature_header)
+          unless Verify.valid?(payload: raw_body, signature: signature, secret: @secret)
+            raise VerificationError, "invalid webhook signature"
+          end
+        end
+
+        # Parse event
+        hash = JSON.parse(raw_body)
+        event = Event.new(hash)
+
+        # Atomic dedup: claim before handlers, commit on success, release on error
+        return event unless claim(event.id)
+
+        begin
+          # Build middleware chain
+          run_handlers = -> { dispatch_handlers(event) }
+          chain = @middleware.reverse.reduce(run_handlers) do |next_fn, mw|
+            -> { mw.call(event, next_fn) }
+          end
+
+          chain.call
+
+          # Promote from pending to seen on success
+          commit_seen(event.id)
+        rescue => e
+          # Release claim so retries can re-attempt
+          release_claim(event.id)
+          raise e
+        end
+
+        event
+      end
+
+      private
+
+      def extract_header(headers, name)
+        if headers.respond_to?(:call)
+          headers.call(name)
+        elsif headers.respond_to?(:[])
+          # Try exact match first, then case-insensitive
+          headers[name] || headers[name.downcase] || headers[name.upcase]
+        end
+      end
+
+      # Returns true if the event was claimed (caller should process it).
+      # Returns false if already seen or in-flight.
+      def claim(event_id)
+        return true if @dedup_window_size <= 0 || event_id.nil?
+
+        @mutex.synchronize do
+          return false if @dedup_seen.key?(event_id) || @dedup_pending.key?(event_id)
+          @dedup_pending[event_id] = true
+          true
+        end
+      end
+
+      # Promote from pending to seen after successful handling.
+      def commit_seen(event_id)
+        return if @dedup_window_size <= 0 || event_id.nil?
+
+        @mutex.synchronize do
+          @dedup_pending.delete(event_id)
+
+          if @dedup_order.size >= @dedup_window_size
+            oldest = @dedup_order.shift
+            @dedup_seen.delete(oldest)
+          end
+
+          @dedup_seen[event_id] = true
+          @dedup_order << event_id
+        end
+      end
+
+      # Release claim so retries can re-attempt.
+      def release_claim(event_id)
+        return if event_id.nil?
+
+        @mutex.synchronize do
+          @dedup_pending.delete(event_id)
+        end
+      end
+
+      def dispatch_handlers(event)
+        matched = []
+
+        @handlers.each do |pattern, handlers|
+          matched.concat(handlers) if match_pattern?(pattern, event.kind)
+        end
+
+        matched.concat(@any_handlers)
+
+        matched.each { |handler| handler.call(event) }
+      end
+
+      def match_pattern?(pattern, value)
+        return false if value.nil?
+        return true if pattern == value
+
+        # Convert glob pattern to regex
+        regex_str = pattern.split("*", -1).map { |part| Regexp.escape(part) }.join(".*")
+        Regexp.new("\\A#{regex_str}\\z").match?(value)
+      end
+    end
+  end
+end

data/lib/basecamp/webhooks/verify.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Basecamp
+  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/basecamp.rb

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "zeitwerk"
+
+# Set up Zeitwerk loader
+loader = Zeitwerk::Loader.for_gem
+# No custom inflections - use standard Ruby camelcase (Http, Oauth, etc.)
+
+# Ignore hand-written services - we use generated services instead (spec-conformant)
+# EXCEPT: base_service.rb (infrastructure) and authorization_service.rb (OAuth, not in spec)
+loader.ignore("#{__dir__}/basecamp/services")
+
+# Collapse the generated directory so Basecamp::Generated::Services becomes Basecamp::Services
+loader.collapse("#{__dir__}/basecamp/generated")
+
+# Ignore errors.rb - it defines multiple classes, loaded explicitly below
+loader.ignore("#{__dir__}/basecamp/errors.rb")
+# Ignore auth_strategy.rb - defines both AuthStrategy and BearerAuth
+loader.ignore("#{__dir__}/basecamp/auth_strategy.rb")
+# Ignore operation_info.rb - defines both OperationInfo and OperationResult
+loader.ignore("#{__dir__}/basecamp/operation_info.rb")
+loader.setup
+
+# Load infrastructure that generated services depend on
+require_relative "basecamp/errors"
+require_relative "basecamp/auth_strategy"
+require_relative "basecamp/operation_info"
+require_relative "basecamp/services/base_service"
+require_relative "basecamp/services/authorization_service"
+
+# Load generated types if available
+begin
+  require_relative "basecamp/generated/types"
+rescue LoadError
+  # Generated types not available yet
+end
+
+# Main entry point for the Basecamp SDK.
+#
+# The SDK follows a Client -> AccountClient pattern:
+# - Client: Holds shared resources (HTTP client, token provider, hooks)
+# - AccountClient: Bound to a specific account ID, provides service accessors
+#
+# @example Basic usage
+#   config = Basecamp::Config.new(base_url: "https://3.basecampapi.com")
+#   token = Basecamp::StaticTokenProvider.new(ENV["BASECAMP_TOKEN"])
+#
+#   client = Basecamp::Client.new(config: config, token_provider: token)
+#   account = client.for_account("12345")
+#
+#   # Use services (returns lazy Enumerator)
+#   projects = account.projects.list.to_a
+#
+# @example With hooks for logging
+#   class MyHooks
+#     include Basecamp::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 = Basecamp::Client.new(config: config, token_provider: token, hooks: MyHooks.new)
+module Basecamp
+  # Creates a new Basecamp client.
+  #
+  # This is a convenience method that creates a Client with the given options.
+  #
+  # @param access_token [String, nil] OAuth access token
+  # @param auth [AuthStrategy, nil] custom authentication strategy
+  # @param account_id [String, nil] Basecamp account ID (optional)
+  # @param base_url [String] Base URL for API requests
+  # @param hooks [Hooks, nil] Observability hooks
+  # @return [Client, AccountClient] Client if no account_id, AccountClient if account_id provided
+  #
+  # @example With access token
+  #   client = Basecamp.client(access_token: "abc123", account_id: "12345")
+  #   projects = client.projects.list.to_a
+  #
+  # @example With custom auth strategy
+  #   client = Basecamp.client(auth: MyCustomAuth.new, account_id: "12345")
+  def self.client(
+    access_token: nil,
+    auth: nil,
+    account_id: 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)
+
+    client = 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
+
+    account_id ? client.for_account(account_id) : client
+  end
+end

data/scripts/generate-metadata.rb

@@ -0,0 +1,106 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# Extracts x-basecamp-* 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/ruby/generate-metadata.rb > lib/basecamp/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://basecamp.com/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-basecamp-retry
+    if (retry_config = operation['x-basecamp-retry'])
+      metadata['retry'] = {
+        'maxAttempts' => retry_config['maxAttempts'],
+        'baseDelayMs' => retry_config['baseDelayMs'],
+        'backoff' => retry_config['backoff'],
+        'retryOn' => retry_config['retryOn']
+      }
+    end
+
+    # Extract x-basecamp-pagination
+    if (pagination = operation['x-basecamp-pagination'])
+      metadata['pagination'] = {
+        'style' => pagination['style'],
+        'pageParam' => pagination['pageParam'],
+        'totalCountHeader' => pagination['totalCountHeader'],
+        'maxPageSize' => pagination['maxPageSize']
+      }.compact
+    end
+
+    # Extract x-basecamp-idempotent
+    if (idempotent = operation['x-basecamp-idempotent'])
+      metadata['idempotent'] = {
+        'keySupported' => idempotent['keySupported'],
+        'keyHeader' => idempotent['keyHeader'],
+        'natural' => idempotent['natural']
+      }.compact
+    end
+
+    # Extract x-basecamp-sensitive
+    if (sensitive = operation['x-basecamp-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