basecamp-sdk 0.2.1

data/lib/basecamp/client.rb

@@ -0,0 +1,428 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Main client for the Basecamp API.
+  #
+  # Client holds shared resources and is used to create AccountClient instances
+  # for specific Basecamp accounts via the {#for_account} method.
+  #
+  # @example Basic usage
+  #   config = Basecamp::Config.from_env
+  #   token_provider = Basecamp::StaticTokenProvider.new(ENV["BASECAMP_ACCESS_TOKEN"])
+  #   client = Basecamp::Client.new(config: config, token_provider: token_provider)
+  #
+  #   # Get authorization info (account-independent)
+  #   auth = client.authorization.get
+  #
+  #   # Work with a specific account
+  #   account = client.for_account("12345")
+  #   projects = account.projects.list
+  #
+  # @example With custom hooks
+  #   require "logger"
+  #   logger = Logger.new($stdout)
+  #   hooks = Basecamp::LoggerHooks.new(logger)
+  #
+  #   client = Basecamp::Client.new(
+  #     config: config,
+  #     token_provider: token_provider,
+  #     hooks: hooks
+  #   )
+  class Client
+    # @return [Config] client configuration
+    attr_reader :config
+
+    # Creates a new Basecamp API client.
+    #
+    # @param config [Config] configuration settings
+    # @param token_provider [TokenProvider, nil] OAuth token provider (deprecated, use auth_strategy)
+    # @param auth_strategy [AuthStrategy, nil] authentication strategy
+    # @param hooks [Hooks, nil] observability hooks
+    def initialize(config:, token_provider: nil, auth_strategy: nil, hooks: nil)
+      raise ArgumentError, "provide either token_provider or auth_strategy, not both" if token_provider && auth_strategy
+      raise ArgumentError, "provide token_provider or auth_strategy" if !token_provider && !auth_strategy
+
+      @config = config
+      @hooks = hooks || NoopHooks.new
+      @http = Http.new(config: config, token_provider: token_provider, auth_strategy: auth_strategy, hooks: @hooks)
+      @mutex = Mutex.new
+    end
+
+    # Returns an AccountClient bound to the specified Basecamp account.
+    #
+    # The Basecamp API requires an account ID in the URL path
+    # (e.g., https://3.basecampapi.com/12345/projects.json).
+    #
+    # @param account_id [String, Integer] the Basecamp account ID
+    # @return [AccountClient]
+    # @raise [ArgumentError] if account_id is empty or non-numeric
+    #
+    # @example
+    #   account = client.for_account("12345")
+    #   projects = account.projects.list
+    def for_account(account_id)
+      account_id = account_id.to_s
+      raise ArgumentError, "account_id cannot be empty" if account_id.empty?
+      raise ArgumentError, "account_id must be numeric, got: #{account_id}" unless account_id.match?(/\A\d+\z/)
+
+      AccountClient.new(parent: self, account_id: account_id)
+    end
+
+    # Returns the AuthorizationService for authorization operations.
+    # This is the only service available directly on Client, as it doesn't require
+    # an account context. All other services require an AccountClient via {#for_account}.
+    #
+    # @return [Services::AuthorizationService]
+    def authorization
+      @mutex.synchronize do
+        @authorization ||= Services::AuthorizationService.new(self)
+      end
+    end
+
+    # @api private
+    # Returns the HTTP client for making requests.
+    # @return [Http]
+    attr_reader :http
+
+    # @api private
+    # Returns the observability hooks.
+    # @return [Hooks]
+    attr_reader :hooks
+
+    # @api private
+    # Returns nil since Client is not bound to an account.
+    # @return [nil]
+    def account_id
+      nil
+    end
+  end
+
+  # HTTP client bound to a specific Basecamp account.
+  #
+  # Create an AccountClient using {Client#for_account}.
+  # All API operations that require an account context use this class.
+  #
+  # @example
+  #   account = client.for_account("12345")
+  #
+  #   # List projects
+  #   account.projects.list.each do |project|
+  #     puts project["name"]
+  #   end
+  #
+  #   # Create a todo
+  #   account.todos.create(
+  #     project_id: 123,
+  #     todolist_id: 456,
+  #     content: "New task"
+  #   )
+  class AccountClient
+    # @return [String] the account ID this client is bound to
+    attr_reader :account_id
+
+    # @api private
+    # @param parent [Client] the parent client
+    # @param account_id [String] the account ID
+    def initialize(parent:, account_id:)
+      @parent = parent
+      @account_id = account_id
+      @services = {}
+      @mutex = Mutex.new
+    end
+
+    # @return [Config] client configuration
+    def config
+      @parent.config
+    end
+
+    # @api private
+    # @return [Http] the HTTP client
+    def http
+      @parent.http
+    end
+
+    # @api private
+    # @return [Hooks] the observability hooks
+    def hooks
+      @parent.hooks
+    end
+
+    # Performs a GET request scoped to this account.
+    # @param path [String] URL path (without account prefix)
+    # @param params [Hash] query parameters
+    # @return [Response]
+    def get(path, params: {})
+      @parent.http.get(account_path(path), params: params)
+    end
+
+    # Performs a POST request scoped to this account.
+    # @param path [String] URL path (without account prefix)
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def post(path, body: nil)
+      @parent.http.post(account_path(path), body: body)
+    end
+
+    # Performs a PUT request scoped to this account.
+    # @param path [String] URL path (without account prefix)
+    # @param body [Hash, nil] request body
+    # @return [Response]
+    def put(path, body: nil)
+      @parent.http.put(account_path(path), body: body)
+    end
+
+    # Performs a DELETE request scoped to this account.
+    # @param path [String] URL path (without account prefix)
+    # @return [Response]
+    def delete(path)
+      @parent.http.delete(account_path(path))
+    end
+
+    # Performs a POST request with raw binary data scoped to this account.
+    # Used for file uploads (attachments).
+    # @param path [String] URL path (without account prefix)
+    # @param body [String, IO] raw binary data
+    # @param content_type [String] MIME content type
+    # @return [Response]
+    def post_raw(path, body:, content_type:)
+      @parent.http.post_raw(account_path(path), body: body, content_type: content_type)
+    end
+
+    # Fetches all pages of a paginated resource.
+    # @param path [String] URL path (without account prefix)
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate(path, params: {}, &)
+      @parent.http.paginate(account_path(path), params: params, &)
+    end
+
+    # Fetches all pages of a paginated resource, extracting items from a key.
+    # Use this for endpoints that return objects like { "events": [...] }.
+    # @param path [String] URL path (without account prefix)
+    # @param key [String] the key containing the array of items
+    # @param params [Hash] query parameters
+    # @yield [Hash] each item from the response
+    # @return [Enumerator] if no block given
+    def paginate_key(path, key:, params: {}, &)
+      @parent.http.paginate_key(account_path(path), key: key, params: params, &)
+    end
+
+    # @!group Services
+
+    # @return [Services::ProjectsService]
+    def projects
+      service(:projects) { Services::ProjectsService.new(self) }
+    end
+
+    # @return [Services::TodosService]
+    def todos
+      service(:todos) { Services::TodosService.new(self) }
+    end
+
+    # @return [Services::TodosetsService]
+    def todosets
+      service(:todosets) { Services::TodosetsService.new(self) }
+    end
+
+    # @return [Services::TodolistsService]
+    def todolists
+      service(:todolists) { Services::TodolistsService.new(self) }
+    end
+
+    # @return [Services::PeopleService]
+    def people
+      service(:people) { Services::PeopleService.new(self) }
+    end
+
+    # @return [Services::CommentsService]
+    def comments
+      service(:comments) { Services::CommentsService.new(self) }
+    end
+
+    # @return [Services::MessagesService]
+    def messages
+      service(:messages) { Services::MessagesService.new(self) }
+    end
+
+    # @return [Services::MessageBoardsService]
+    def message_boards
+      service(:message_boards) { Services::MessageBoardsService.new(self) }
+    end
+
+    # @return [Services::WebhooksService]
+    def webhooks
+      service(:webhooks) { Services::WebhooksService.new(self) }
+    end
+
+    # @return [Services::CampfiresService]
+    def campfires
+      service(:campfires) { Services::CampfiresService.new(self) }
+    end
+
+    # @return [Services::SchedulesService]
+    def schedules
+      service(:schedules) { Services::SchedulesService.new(self) }
+    end
+
+    # @return [Services::VaultsService]
+    def vaults
+      service(:vaults) { Services::VaultsService.new(self) }
+    end
+
+    # @return [Services::RecordingsService]
+    def recordings
+      service(:recordings) { Services::RecordingsService.new(self) }
+    end
+
+    # @return [Services::DocumentsService]
+    def documents
+      service(:documents) { Services::DocumentsService.new(self) }
+    end
+
+    # @return [Services::UploadsService]
+    def uploads
+      service(:uploads) { Services::UploadsService.new(self) }
+    end
+
+    # @return [Services::AttachmentsService]
+    def attachments
+      service(:attachments) { Services::AttachmentsService.new(self) }
+    end
+
+    # @return [Services::CheckinsService]
+    def checkins
+      service(:checkins) { Services::CheckinsService.new(self) }
+    end
+
+    # @return [Services::ForwardsService]
+    def forwards
+      service(:forwards) { Services::ForwardsService.new(self) }
+    end
+
+    # @return [Services::CardTablesService]
+    def card_tables
+      service(:card_tables) { Services::CardTablesService.new(self) }
+    end
+
+    # @return [Services::CardsService]
+    def cards
+      service(:cards) { Services::CardsService.new(self) }
+    end
+
+    # @return [Services::CardColumnsService]
+    def card_columns
+      service(:card_columns) { Services::CardColumnsService.new(self) }
+    end
+
+    # @return [Services::CardStepsService]
+    def card_steps
+      service(:card_steps) { Services::CardStepsService.new(self) }
+    end
+
+    # @return [Services::TemplatesService]
+    def templates
+      service(:templates) { Services::TemplatesService.new(self) }
+    end
+
+    # @return [Services::EventsService]
+    def events
+      service(:events) { Services::EventsService.new(self) }
+    end
+
+    # @return [Services::ClientApprovalsService]
+    def client_approvals
+      service(:client_approvals) { Services::ClientApprovalsService.new(self) }
+    end
+
+    # @return [Services::ClientCorrespondencesService]
+    def client_correspondences
+      service(:client_correspondences) { Services::ClientCorrespondencesService.new(self) }
+    end
+
+    # @return [Services::ClientRepliesService]
+    def client_replies
+      service(:client_replies) { Services::ClientRepliesService.new(self) }
+    end
+
+    # @return [Services::LineupService]
+    def lineup
+      service(:lineup) { Services::LineupService.new(self) }
+    end
+
+    # @return [Services::MessageTypesService]
+    def message_types
+      service(:message_types) { Services::MessageTypesService.new(self) }
+    end
+
+    # @return [Services::ToolsService]
+    def tools
+      service(:tools) { Services::ToolsService.new(self) }
+    end
+
+    # @return [Services::SubscriptionsService]
+    def subscriptions
+      service(:subscriptions) { Services::SubscriptionsService.new(self) }
+    end
+
+    # @return [Services::SearchService]
+    def search
+      service(:search) { Services::SearchService.new(self) }
+    end
+
+    # @return [Services::ReportsService]
+    def reports
+      service(:reports) { Services::ReportsService.new(self) }
+    end
+
+    # @return [Services::TimelineService]
+    def timeline
+      service(:timeline) { Services::TimelineService.new(self) }
+    end
+
+    # @return [Services::TimesheetsService]
+    def timesheets
+      service(:timesheets) { Services::TimesheetsService.new(self) }
+    end
+
+    # @return [Services::ClientVisibilityService]
+    def client_visibility
+      service(:client_visibility) { Services::ClientVisibilityService.new(self) }
+    end
+
+    # @return [Services::TodolistGroupsService]
+    def todolist_groups
+      service(:todolist_groups) { Services::TodolistGroupsService.new(self) }
+    end
+
+    # @return [Services::BoostsService]
+    def boosts
+      service(:boosts) { Services::BoostsService.new(self) }
+    end
+
+    # @!endgroup
+
+    private
+
+    def account_path(path)
+      return path if path.start_with?("http://", "https://")
+
+      path = "/#{path}" unless path.start_with?("/")
+
+      # Guard against double-prefixing
+      prefix = "/#{@account_id}"
+      if path.start_with?(prefix)
+        rest = path[prefix.length..]
+        return path if rest.empty? || rest.start_with?("/", "?")
+      end
+
+      "/#{@account_id}#{path}"
+    end
+
+    def service(name)
+      @mutex.synchronize do
+        @services[name] ||= yield
+      end
+    end
+  end
+end

data/lib/basecamp/config.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Basecamp
+  # Configuration for the Basecamp API client.
+  #
+  # @example Creating config with defaults
+  #   config = Basecamp::Config.new
+  #
+  # @example Creating config with custom values
+  #   config = Basecamp::Config.new(
+  #     base_url: "https://3.basecampapi.com",
+  #     timeout: 60,
+  #     max_retries: 3
+  #   )
+  #
+  # @example Loading config from environment
+  #   config = Basecamp::Config.from_env
+  class Config
+    # @return [String] API base URL
+    attr_accessor :base_url
+
+    # @return [Integer] request timeout in seconds
+    attr_accessor :timeout
+
+    # @return [Integer] maximum retry attempts for GET requests
+    attr_accessor :max_retries
+
+    # @return [Float] initial backoff delay in seconds
+    attr_accessor :base_delay
+
+    # @return [Float] maximum jitter to add to delays in seconds
+    attr_accessor :max_jitter
+
+    # @return [Integer] maximum pages to fetch in paginated requests
+    attr_accessor :max_pages
+
+    # Default values
+    DEFAULT_BASE_URL = "https://3.basecampapi.com"
+    DEFAULT_TIMEOUT = 30
+    DEFAULT_MAX_RETRIES = 3
+    DEFAULT_BASE_DELAY = 1.0
+    DEFAULT_MAX_JITTER = 0.1
+    DEFAULT_MAX_PAGES = 10_000
+
+    # Creates a new configuration with the given options.
+    #
+    # @param base_url [String] API base URL
+    # @param timeout [Integer] request timeout in seconds
+    # @param max_retries [Integer] maximum retry attempts
+    # @param base_delay [Float] initial backoff delay
+    # @param max_jitter [Float] maximum jitter
+    # @param max_pages [Integer] maximum pages to fetch
+    def initialize(
+      base_url: DEFAULT_BASE_URL,
+      timeout: DEFAULT_TIMEOUT,
+      max_retries: DEFAULT_MAX_RETRIES,
+      base_delay: DEFAULT_BASE_DELAY,
+      max_jitter: DEFAULT_MAX_JITTER,
+      max_pages: DEFAULT_MAX_PAGES
+    )
+      @base_url = normalize_url(base_url)
+      @timeout = timeout
+      @max_retries = max_retries
+      @base_delay = base_delay
+      @max_jitter = max_jitter
+      @max_pages = max_pages
+
+      unless @base_url == normalize_url(DEFAULT_BASE_URL) || localhost?(@base_url)
+        Basecamp::Security.require_https!(@base_url, "base URL")
+      end
+      validate!
+    end
+
+    # Creates a Config from environment variables.
+    #
+    # Environment variables:
+    # - BASECAMP_BASE_URL: API base URL
+    # - BASECAMP_TIMEOUT: Request timeout in seconds
+    # - BASECAMP_MAX_RETRIES: Maximum retry attempts
+    #
+    # @return [Config]
+    def self.from_env
+      new(
+        base_url: ENV.fetch("BASECAMP_BASE_URL", DEFAULT_BASE_URL),
+        timeout: ENV.fetch("BASECAMP_TIMEOUT", DEFAULT_TIMEOUT).to_i,
+        max_retries: ENV.fetch("BASECAMP_MAX_RETRIES", DEFAULT_MAX_RETRIES).to_i
+      )
+    end
+
+    # Loads configuration from a JSON file, with environment overrides.
+    #
+    # @param path [String] path to JSON config file
+    # @return [Config]
+    def self.from_file(path)
+      data = JSON.parse(File.read(path))
+      config = new(
+        base_url: data["base_url"] || DEFAULT_BASE_URL,
+        timeout: data["timeout"] || DEFAULT_TIMEOUT,
+        max_retries: data["max_retries"] || DEFAULT_MAX_RETRIES
+      )
+      config.load_from_env
+      config
+    rescue Errno::ENOENT
+      from_env
+    end
+
+    # Loads environment variable overrides into this config.
+    # @return [self]
+    def load_from_env
+      @base_url = normalize_url(ENV["BASECAMP_BASE_URL"]) if ENV["BASECAMP_BASE_URL"]
+      @timeout = ENV["BASECAMP_TIMEOUT"].to_i if ENV["BASECAMP_TIMEOUT"]
+      @max_retries = ENV["BASECAMP_MAX_RETRIES"].to_i if ENV["BASECAMP_MAX_RETRIES"]
+      Basecamp::Security.require_https!(@base_url, "base URL") unless localhost?(@base_url)
+      validate!
+      self
+    end
+
+    # Returns the default global config directory.
+    # @return [String]
+    def self.global_config_dir
+      config_dir = ENV["XDG_CONFIG_HOME"] || File.join(Dir.home, ".config")
+      File.join(config_dir, "basecamp")
+    end
+
+    private
+
+    def validate!
+      raise ArgumentError, "timeout must be positive" unless @timeout.is_a?(Numeric) && @timeout > 0
+      raise ArgumentError, "max_retries must be non-negative" unless @max_retries.is_a?(Integer) && @max_retries >= 0
+      raise ArgumentError, "max_pages must be positive" unless @max_pages.is_a?(Integer) && @max_pages > 0
+    end
+
+    def normalize_url(url)
+      url&.chomp("/")
+    end
+
+    def localhost?(url)
+      Basecamp::Security.localhost?(url)
+    end
+  end
+end