basecamp-sdk 0.2.1

data/lib/basecamp/operation_info.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Information about a service operation for observability hooks.
+  OperationInfo = Data.define(:service, :operation, :resource_type, :is_mutation, :project_id, :resource_id) do
+    def initialize(service:, operation:, resource_type: nil, is_mutation: false, project_id: nil, 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/basecamp/request_info.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # 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

data/lib/basecamp/request_result.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # 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/basecamp/security.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Basecamp
+  # 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 Basecamp::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]".
+    #
+    # This is useful for safely logging HTTP requests and responses without
+    # exposing tokens, cookies, or other credentials.
+    #
+    # @param headers [Hash] the headers hash (case-insensitive keys)
+    # @return [Hash] a new hash with sensitive values redacted
+    #
+    # @example
+    #   headers = { "Authorization" => "Bearer token", "Content-Type" => "application/json" }
+    #   safe = Basecamp::Security.redact_headers(headers)
+    #   # => { "Authorization" => "[REDACTED]", "Content-Type" => "application/json" }
+    #
+    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/basecamp/services/attachments_service.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module Basecamp
+  module Services
+    # Service for attachment operations.
+    #
+    # Attachments are used to upload files that can be embedded in rich text
+    # content like messages, comments, and documents. After uploading, you
+    # receive an attachable_sgid that can be used to embed the file in HTML.
+    #
+    # @example Upload a file
+    #   attachment = account.attachments.create(
+    #     filename: "report.pdf",
+    #     content_type: "application/pdf",
+    #     data: file_content
+    #   )
+    #   # Use in HTML: <bc-attachment sgid="#{attachment["attachable_sgid"]}"></bc-attachment>
+    class AttachmentsService < BaseService
+      # Creates an attachment by uploading a file.
+      # Returns an attachable_sgid for embedding the file in rich text content.
+      #
+      # @param filename [String] filename for the uploaded file
+      # @param content_type [String] MIME content type (e.g., "image/png", "application/pdf")
+      # @param data [String] file data
+      # @return [Hash] attachment response with attachable_sgid
+      def create(filename:, content_type:, data:)
+        http_post_raw("/attachments.json?name=#{URI.encode_www_form_component(filename)}", body: data, content_type: content_type).json
+      end
+    end
+  end
+end

data/lib/basecamp/services/authorization_service.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for authorization operations.
+    # This is the only service that doesn't require an account context.
+    #
+    # @example Get authorization info
+    #   auth = client.authorization.get
+    #   puts "Identity: #{auth["identity"]["email_address"]}"
+    #   auth["accounts"].each do |account|
+    #     puts "Account: #{account["name"]} (#{account["id"]})"
+    #   end
+    class AuthorizationService < BaseService
+      # Fallback Launchpad endpoint for authorization
+      LAUNCHPAD_AUTHORIZATION_URL = "https://launchpad.37signals.com/authorization.json"
+
+      # Gets authorization information for the current user.
+      #
+      # Attempts to use the authorization endpoint discovered via OAuth discovery
+      # on the configured base URL. Falls back to Launchpad if discovery fails.
+      #
+      # Returns the authenticated user's identity and list of accounts
+      # they have access to.
+      #
+      # @return [Hash] authorization info with :identity and :accounts
+      # @see https://github.com/basecamp/bc3-api/blob/master/sections/authentication.md
+      def get
+        url = discover_authorization_url
+        response = http.get_absolute(url)
+        response.json
+      end
+
+      private
+
+        def discover_authorization_url
+          # Try OAuth discovery on the configured base URL
+          config = Oauth.discover(http.base_url)
+          # Use issuer as base for authorization.json
+          "#{config.issuer.chomp("/")}/authorization.json"
+        rescue Oauth::OAuthError
+          # Fall back to Launchpad
+          LAUNCHPAD_AUTHORIZATION_URL
+        end
+    end
+  end
+end

data/lib/basecamp/services/base_service.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+require "cgi/escape"
+require_relative "../errors"
+
+module Basecamp
+  module Services
+    # Base service class for Basecamp API services.
+    #
+    # Provides shared functionality for all service classes including:
+    # - HTTP method delegation (http_get, http_post, etc.)
+    # - Path building helpers
+    # - Pagination support
+    #
+    # @example
+    #   class TodosService < BaseService
+    #     def list(project_id:, todolist_id:)
+    #       paginate(bucket_path(project_id, "/todolists/#{todolist_id}/todos.json"))
+    #     end
+    #   end
+    class BaseService
+      # @return [String] the account ID for API requests
+      attr_reader :account_id
+
+      # @param client [Object] the parent client (AccountClient or Client)
+      def initialize(client)
+        @client = client
+        @account_id = client.account_id
+        @hooks = client.hooks
+      end
+
+      protected
+
+      # Wraps a service operation with hooks for observability.
+      # @param service [String] service name (e.g., "projects")
+      # @param operation [String] operation name (e.g., "list")
+      # @param resource_type [String, nil] resource type (e.g., "Project")
+      # @param is_mutation [Boolean] whether this is a write operation
+      # @param project_id [Integer, String, nil] project/bucket ID
+      # @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, project_id: nil, resource_id: nil)
+        info = OperationInfo.new(
+          service: service, operation: operation, resource_type: resource_type,
+          is_mutation: is_mutation, project_id: project_id, 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, project_id: nil, resource_id: nil)
+        info = OperationInfo.new(
+          service: service, operation: operation,
+          is_mutation: is_mutation, project_id: project_id, 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 "Basecamp 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
+
+      # Build a bucket (project) path.
+      # @param project_id [Integer, String] the project/bucket ID
+      # @param path [String] the path suffix
+      # @return [String] the full bucket path
+      def bucket_path(project_id, path)
+        "/buckets/#{project_id}#{path}"
+      end
+
+      # Delegate HTTP methods to the client with http_ prefix to avoid conflicts
+      # with service method names (e.g., service.get vs http_get)
+      # @!method http_get(path, params: {})
+      #   @see AccountClient#get
+      # @!method http_post(path, body: nil)
+      #   @see AccountClient#post
+      # @!method http_put(path, body: nil)
+      #   @see AccountClient#put
+      # @!method http_delete(path)
+      #   @see AccountClient#delete
+      # @!method http_post_raw(path, body:, content_type:)
+      #   @see AccountClient#post_raw
+      # @!method paginate(path, params: {}, &block)
+      #   @see AccountClient#paginate
+      %i[get post put 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
+
+      # Paginate extracting items from a specific key (for object responses)
+      def paginate_key(...)
+        @client.paginate_key(...)
+      end
+    end
+  end
+end

data/lib/basecamp/services/campfires_service.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for campfire (chat) operations.
+    #
+    # Campfires are real-time chat rooms within Basecamp projects.
+    # They contain lines (messages) and can have chatbot integrations.
+    #
+    # @example List all campfires
+    #   account.campfires.list.each do |campfire|
+    #     puts campfire["title"]
+    #   end
+    #
+    # @example Send a message
+    #   line = account.campfires.create_line(
+    #     project_id: 123,
+    #     campfire_id: 456,
+    #     content: "Hello team!"
+    #   )
+    class CampfiresService < BaseService
+      # Lists all campfires across the account.
+      #
+      # @return [Enumerator<Hash>] campfires
+      def list
+        paginate("/chats.json")
+      end
+
+      # Gets a specific campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @return [Hash] campfire data
+      def get(project_id:, campfire_id:)
+        http_get(bucket_path(project_id, "/chats/#{campfire_id}.json")).json
+      end
+
+      # Lists all lines (messages) in a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @return [Enumerator<Hash>] campfire lines
+      def list_lines(project_id:, campfire_id:)
+        paginate(bucket_path(project_id, "/chats/#{campfire_id}/lines.json"))
+      end
+
+      # Gets a specific line (message) from a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param line_id [Integer, String] line ID
+      # @return [Hash] campfire line
+      def get_line(project_id:, campfire_id:, line_id:)
+        http_get(bucket_path(project_id, "/chats/#{campfire_id}/lines/#{line_id}.json")).json
+      end
+
+      # Creates a new line (message) in a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param content [String] plain text message content
+      # @return [Hash] created line
+      def create_line(project_id:, campfire_id:, content:)
+        body = { content: content }
+        http_post(bucket_path(project_id, "/chats/#{campfire_id}/lines.json"), body: body).json
+      end
+
+      # Deletes a line (message) from a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param line_id [Integer, String] line ID
+      # @return [void]
+      def delete_line(project_id:, campfire_id:, line_id:)
+        http_delete(bucket_path(project_id, "/chats/#{campfire_id}/lines/#{line_id}.json"))
+        nil
+      end
+
+      # Lists all chatbots for a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @return [Enumerator<Hash>] chatbots
+      def list_chatbots(project_id:, campfire_id:)
+        paginate(bucket_path(project_id, "/chats/#{campfire_id}/integrations.json"))
+      end
+
+      # Gets a specific chatbot.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param chatbot_id [Integer, String] chatbot ID
+      # @return [Hash] chatbot data
+      def get_chatbot(project_id:, campfire_id:, chatbot_id:)
+        http_get(bucket_path(project_id, "/chats/#{campfire_id}/integrations/#{chatbot_id}.json")).json
+      end
+
+      # Creates a new chatbot for a campfire.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param service_name [String] chatbot name (no spaces, emoji, or non-word characters)
+      # @param command_url [String, nil] HTTPS URL for bot callbacks
+      # @return [Hash] created chatbot with lines_url for posting
+      def create_chatbot(project_id:, campfire_id:, service_name:, command_url: nil)
+        body = compact_params(
+          service_name: service_name,
+          command_url: command_url
+        )
+        http_post(bucket_path(project_id, "/chats/#{campfire_id}/integrations.json"), body: body).json
+      end
+
+      # Updates an existing chatbot.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param chatbot_id [Integer, String] chatbot ID
+      # @param service_name [String] new chatbot name
+      # @param command_url [String, nil] new callback URL
+      # @return [Hash] updated chatbot
+      def update_chatbot(project_id:, campfire_id:, chatbot_id:, service_name:, command_url: nil)
+        body = compact_params(
+          service_name: service_name,
+          command_url: command_url
+        )
+        http_put(bucket_path(project_id, "/chats/#{campfire_id}/integrations/#{chatbot_id}.json"), body: body).json
+      end
+
+      # Deletes a chatbot.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param campfire_id [Integer, String] campfire ID
+      # @param chatbot_id [Integer, String] chatbot ID
+      # @return [void]
+      def delete_chatbot(project_id:, campfire_id:, chatbot_id:)
+        http_delete(bucket_path(project_id, "/chats/#{campfire_id}/integrations/#{chatbot_id}.json"))
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/card_columns_service.rb

@@ -0,0 +1,106 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for card column operations.
+    #
+    # Columns are lists within a card table that contain cards.
+    #
+    # @example Create a column
+    #   column = account.card_columns.create(
+    #     project_id: 123,
+    #     card_table_id: 456,
+    #     title: "In Review"
+    #   )
+    #
+    # @example Set column color
+    #   account.card_columns.set_color(project_id: 123, column_id: 456, color: "blue")
+    class CardColumnsService < BaseService
+      # Gets a column by ID.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param column_id [Integer, String] column ID
+      # @return [Hash] column data
+      def get(project_id:, column_id:)
+        http_get(bucket_path(project_id, "/card_tables/columns/#{column_id}.json")).json
+      end
+
+      # Creates a new column in a card table.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param card_table_id [Integer, String] card table ID
+      # @param title [String] column title
+      # @param description [String, nil] column description
+      # @return [Hash] created column
+      def create(project_id:, card_table_id:, title:, description: nil)
+        body = compact_params(
+          title: title,
+          description: description
+        )
+        http_post(bucket_path(project_id, "/card_tables/#{card_table_id}/columns.json"), body: body).json
+      end
+
+      # Updates an existing column.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param column_id [Integer, String] column ID
+      # @param title [String, nil] new title
+      # @param description [String, nil] new description
+      # @return [Hash] updated column
+      def update(project_id:, column_id:, title: nil, description: nil)
+        body = compact_params(
+          title: title,
+          description: description
+        )
+        http_put(bucket_path(project_id, "/card_tables/columns/#{column_id}.json"), body: body).json
+      end
+
+      # Moves a column within a card table.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param card_table_id [Integer, String] card table ID
+      # @param source_id [Integer, String] column ID to move
+      # @param target_id [Integer, String] column ID to move relative to
+      # @param position [Integer, nil] position relative to target
+      # @return [void]
+      def move(project_id:, card_table_id:, source_id:, target_id:, position: nil)
+        body = compact_params(
+          source_id: source_id,
+          target_id: target_id,
+          position: position
+        )
+        http_post(bucket_path(project_id, "/card_tables/#{card_table_id}/moves.json"), body: body)
+        nil
+      end
+
+      # Sets the color of a column.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param column_id [Integer, String] column ID
+      # @param color [String] color name (white, red, orange, yellow, green, blue, aqua, purple, gray, pink, brown)
+      # @return [Hash] updated column
+      def set_color(project_id:, column_id:, color:)
+        http_put(bucket_path(project_id, "/card_tables/columns/#{column_id}/color.json"),
+                 body: { color: color }).json
+      end
+
+      # Adds an on-hold section to a column.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param column_id [Integer, String] column ID
+      # @return [Hash] updated column
+      def enable_on_hold(project_id:, column_id:)
+        http_post(bucket_path(project_id, "/card_tables/columns/#{column_id}/on_hold.json")).json
+      end
+
+      # Removes the on-hold section from a column.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param column_id [Integer, String] column ID
+      # @return [Hash] updated column
+      def disable_on_hold(project_id:, column_id:)
+        http_delete(bucket_path(project_id, "/card_tables/columns/#{column_id}/on_hold.json")).json
+      end
+    end
+  end
+end