basecamp-sdk 0.4.0 → 0.6.0

data/lib/basecamp/errors.rb

@@ -1,294 +0,0 @@
-# frozen_string_literal: true
-
-# Error types and codes for the Basecamp SDK.
-module Basecamp
-  # Error codes for API responses
-  module ErrorCode
-    USAGE = "usage"
-    NOT_FOUND = "not_found"
-    AUTH = "auth_required"
-    FORBIDDEN = "forbidden"
-    RATE_LIMIT = "rate_limit"
-    NETWORK = "network"
-    API = "api_error"
-    AMBIGUOUS = "ambiguous"
-    VALIDATION = "validation"
-  end
-
-  # Exit codes for CLI tools
-  module ExitCode
-    OK = 0
-    USAGE = 1
-    NOT_FOUND = 2
-    AUTH = 3
-    FORBIDDEN = 4
-    RATE_LIMIT = 5
-    NETWORK = 6
-    API = 7
-    AMBIGUOUS = 8
-    VALIDATION = 9
-  end
-
-  # Base error class for all Basecamp SDK errors.
-  # Provides structured error handling with codes, hints, and CLI exit codes.
-  #
-  # @example Catching errors
-  #   begin
-  #     client.projects.list
-  #   rescue Basecamp::Error => e
-  #     puts "#{e.code}: #{e.message}"
-  #     puts "Hint: #{e.hint}" if e.hint
-  #     exit e.exit_code
-  #   end
-  class Error < StandardError
-    # @return [String] error category code
-    attr_reader :code
-
-    # @return [String, nil] user-friendly hint for resolving the error
-    attr_reader :hint
-
-    # @return [Integer, nil] HTTP status code that caused the error
-    attr_reader :http_status
-
-    # @return [Boolean] whether the operation can be retried
-    attr_reader :retryable
-
-    # @return [Integer, nil] seconds to wait before retrying (for rate limits)
-    attr_reader :retry_after
-
-    # @return [String, nil] X-Request-Id from the response
-    attr_reader :request_id
-
-    # @return [Exception, nil] original error that caused this error
-    attr_reader :cause
-
-    # @param code [String] error category code
-    # @param message [String] error message
-    # @param hint [String, nil] user-friendly hint
-    # @param http_status [Integer, nil] HTTP status code
-    # @param retryable [Boolean] whether operation can be retried
-    # @param retry_after [Integer, nil] seconds to wait before retry
-    # @param request_id [String, nil] X-Request-Id from response
-    # @param cause [Exception, nil] underlying cause
-    def initialize(code:, message:, hint: nil, http_status: nil, retryable: false, retry_after: nil, request_id: nil, cause: nil)
-      super(message)
-      @code = code
-      @hint = hint
-      @http_status = http_status
-      @retryable = retryable
-      @retry_after = retry_after
-      @request_id = request_id
-      @cause = cause
-    end
-
-    # Returns the exit code for CLI applications.
-    # @return [Integer]
-    def exit_code
-      self.class.exit_code_for(@code)
-    end
-
-    # Returns whether this error can be retried.
-    # @return [Boolean]
-    def retryable?
-      @retryable
-    end
-
-    # Maps error codes to exit codes.
-    # @param code [String]
-    # @return [Integer]
-    def self.exit_code_for(code)
-      case code
-      when ErrorCode::USAGE then ExitCode::USAGE
-      when ErrorCode::NOT_FOUND then ExitCode::NOT_FOUND
-      when ErrorCode::AUTH then ExitCode::AUTH
-      when ErrorCode::FORBIDDEN then ExitCode::FORBIDDEN
-      when ErrorCode::RATE_LIMIT then ExitCode::RATE_LIMIT
-      when ErrorCode::NETWORK then ExitCode::NETWORK
-      when ErrorCode::API then ExitCode::API
-      when ErrorCode::AMBIGUOUS then ExitCode::AMBIGUOUS
-      when ErrorCode::VALIDATION then ExitCode::VALIDATION
-      else ExitCode::API
-      end
-    end
-  end
-
-  # Raised when there's a usage error (invalid arguments, missing config).
-  class UsageError < Error
-    def initialize(message, hint: nil)
-      super(code: ErrorCode::USAGE, message: message, hint: hint)
-    end
-  end
-
-  # Raised when a resource is not found (404).
-  class NotFoundError < Error
-    def initialize(resource, identifier, hint: nil)
-      super(
-        code: ErrorCode::NOT_FOUND,
-        message: "#{resource} not found: #{identifier}",
-        hint: hint,
-        http_status: 404
-      )
-    end
-  end
-
-  # Raised when authentication fails (401).
-  class AuthError < Error
-    def initialize(message = "Authentication required", hint: nil, cause: nil)
-      super(
-        code: ErrorCode::AUTH,
-        message: message,
-        hint: hint || "Check your access token or refresh it if expired",
-        http_status: 401,
-        cause: cause
-      )
-    end
-  end
-
-  # Raised when access is denied (403).
-  class ForbiddenError < Error
-    def initialize(message = "Access denied", hint: nil)
-      super(
-        code: ErrorCode::FORBIDDEN,
-        message: message,
-        hint: hint || "You do not have permission to access this resource",
-        http_status: 403
-      )
-    end
-
-    # Creates a forbidden error due to insufficient OAuth scope.
-    def self.insufficient_scope
-      new("Access denied: insufficient scope", hint: "Re-authenticate with full scope")
-    end
-  end
-
-  # Raised when rate limited (429).
-  class RateLimitError < Error
-    def initialize(retry_after: nil, cause: nil)
-      hint = retry_after ? "Try again in #{retry_after} seconds" : "Please slow down requests"
-      super(
-        code: ErrorCode::RATE_LIMIT,
-        message: "Rate limit exceeded",
-        hint: hint,
-        http_status: 429,
-        retryable: true,
-        retry_after: retry_after,
-        cause: cause
-      )
-    end
-  end
-
-  # Raised when there's a network error (connection, timeout, DNS).
-  class NetworkError < Error
-    def initialize(message = "Network error", cause: nil)
-      super(
-        code: ErrorCode::NETWORK,
-        message: message,
-        hint: cause&.message || "Check your network connection",
-        retryable: true,
-        cause: cause
-      )
-    end
-  end
-
-  # Raised for generic API errors.
-  class APIError < Error
-    def initialize(message, http_status: nil, hint: nil, retryable: false, cause: nil)
-      super(
-        code: ErrorCode::API,
-        message: message,
-        hint: hint,
-        http_status: http_status,
-        retryable: retryable,
-        cause: cause
-      )
-    end
-
-    # Creates an APIError from an HTTP status code.
-    # @param status [Integer] HTTP status code
-    # @param message [String, nil] optional error message
-    # @return [APIError]
-    def self.from_status(status, message = nil)
-      message ||= "Request failed (HTTP #{status})"
-      retryable = status >= 500 && status < 600
-      new(message, http_status: status, retryable: retryable)
-    end
-  end
-
-  # Raised when a name/identifier matches multiple resources.
-  class AmbiguousError < Error
-    # @return [Array<String>] list of matching resources
-    attr_reader :matches
-
-    def initialize(resource, matches: [])
-      @matches = matches
-      hint = if matches.any? && matches.length <= 5
-               "Did you mean: #{matches.join(", ")}"
-      else
-               "Be more specific"
-      end
-      super(
-        code: ErrorCode::AMBIGUOUS,
-        message: "Ambiguous #{resource}",
-        hint: hint
-      )
-    end
-  end
-
-  # Raised for validation errors (400, 422).
-  class ValidationError < Error
-    def initialize(message, hint: nil, http_status: 400)
-      super(
-        code: ErrorCode::VALIDATION,
-        message: message,
-        hint: hint,
-        http_status: http_status
-      )
-    end
-  end
-
-  # Maps an HTTP response to the appropriate error class.
-  #
-  # @param status [Integer] HTTP status code
-  # @param body [String, nil] response body (will attempt JSON parse)
-  # @param retry_after [Integer, nil] Retry-After header value
-  # @return [Error]
-  def self.error_from_response(status, body = nil, retry_after: nil)
-    message = parse_error_message(body) || "Request failed"
-
-    case status
-    when 400, 422
-      ValidationError.new(message, http_status: status)
-    when 401
-      AuthError.new(message)
-    when 403
-      ForbiddenError.new(message)
-    when 404
-      NotFoundError.new("Resource", "unknown")
-    when 429
-      RateLimitError.new(retry_after: retry_after)
-    when 500
-      APIError.new("Server error (500)", http_status: 500, retryable: true)
-    when 502, 503, 504
-      APIError.new("Gateway error (#{status})", http_status: status, retryable: true)
-    else
-      APIError.from_status(status, message)
-    end
-  end
-
-  # Parses error message from response body.
-  # @param body [String, nil]
-  # @return [String, nil]
-  def self.parse_error_message(body)
-    return nil if body.nil? || body.empty?
-
-    # Guard against oversized error bodies before parsing
-    Basecamp::Security.check_body_size!(body, Basecamp::Security::MAX_ERROR_BODY_BYTES, "Error")
-
-    data = JSON.parse(body)
-    msg = data["error"] || data["message"]
-    msg ? Basecamp::Security.truncate(msg) : nil
-  rescue JSON::ParserError, Basecamp::APIError
-    # Return nil on parse errors or oversized bodies to preserve normal error type mapping
-    nil
-  end
-end

data/lib/basecamp/oauth/types.rb

@@ -1,133 +0,0 @@
-# frozen_string_literal: true
-
-module Basecamp
-  module Oauth
-    # OAuth 2 server configuration from discovery endpoint.
-    #
-    # @attr issuer [String] The authorization server's issuer identifier
-    # @attr authorization_endpoint [String] URL of the authorization endpoint
-    # @attr token_endpoint [String] URL of the token endpoint
-    # @attr registration_endpoint [String, nil] URL of the dynamic client registration endpoint
-    # @attr scopes_supported [Array<String>, nil] List of OAuth 2 scopes supported
-    Config = Data.define(
-      :issuer,
-      :authorization_endpoint,
-      :token_endpoint,
-      :registration_endpoint,
-      :scopes_supported
-    ) do
-      def initialize(
-        issuer:,
-        authorization_endpoint:,
-        token_endpoint:,
-        registration_endpoint: nil,
-        scopes_supported: nil
-      )
-        super
-      end
-    end
-
-    # OAuth 2 access token response.
-    #
-    # @attr access_token [String] The access token string
-    # @attr token_type [String] Token type (usually "Bearer")
-    # @attr refresh_token [String, nil] The refresh token string
-    # @attr expires_in [Integer, nil] Lifetime of the access token in seconds
-    # @attr expires_at [Time, nil] Calculated expiration time
-    # @attr scope [String, nil] OAuth scope granted
-    Token = Data.define(
-      :access_token,
-      :token_type,
-      :refresh_token,
-      :expires_in,
-      :expires_at,
-      :scope
-    ) do
-      def initialize(
-        access_token:,
-        token_type: "Bearer",
-        refresh_token: nil,
-        expires_in: nil,
-        expires_at: nil,
-        scope: nil
-      )
-        # Calculate expires_at from expires_in if not provided
-        calculated_expires_at = expires_at || (expires_in ? Time.now + expires_in : nil)
-        super(
-          access_token: access_token,
-          token_type: token_type,
-          refresh_token: refresh_token,
-          expires_in: expires_in,
-          expires_at: calculated_expires_at,
-          scope: scope
-        )
-      end
-
-      # Checks if the token is expired or about to expire.
-      #
-      # @param buffer_seconds [Integer] Buffer time before actual expiration (default: 60)
-      # @return [Boolean] true if expired or will expire within buffer time
-      def expired?(buffer_seconds = 60)
-        return false unless expires_at
-
-        Time.now + buffer_seconds >= expires_at
-      end
-    end
-
-    # Parameters for exchanging an authorization code for tokens.
-    #
-    # @attr token_endpoint [String] URL of the token endpoint
-    # @attr code [String] The authorization code received from the authorization server
-    # @attr redirect_uri [String] The redirect URI used in the authorization request
-    # @attr client_id [String] The client identifier
-    # @attr client_secret [String, nil] The client secret (optional for public clients)
-    # @attr code_verifier [String, nil] PKCE code verifier (optional)
-    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
-    ExchangeRequest = Data.define(
-      :token_endpoint,
-      :code,
-      :redirect_uri,
-      :client_id,
-      :client_secret,
-      :code_verifier,
-      :use_legacy_format
-    ) do
-      def initialize(
-        token_endpoint:,
-        code:,
-        redirect_uri:,
-        client_id:,
-        client_secret: nil,
-        code_verifier: nil,
-        use_legacy_format: false
-      )
-        super
-      end
-    end
-
-    # Parameters for refreshing an access token.
-    #
-    # @attr token_endpoint [String] URL of the token endpoint
-    # @attr refresh_token [String] The refresh token
-    # @attr client_id [String, nil] The client identifier (optional)
-    # @attr client_secret [String, nil] The client secret (optional)
-    # @attr use_legacy_format [Boolean] Use Launchpad's non-standard token format
-    RefreshRequest = Data.define(
-      :token_endpoint,
-      :refresh_token,
-      :client_id,
-      :client_secret,
-      :use_legacy_format
-    ) do
-      def initialize(
-        token_endpoint:,
-        refresh_token:,
-        client_id: nil,
-        client_secret: nil,
-        use_legacy_format: false
-      )
-        super
-      end
-    end
-  end
-end

data/lib/basecamp/services/attachments_service.rb

@@ -1,33 +0,0 @@
-# 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/campfires_service.rb

@@ -1,141 +0,0 @@
-# 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

@@ -1,106 +0,0 @@
-# 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