basecamp-sdk 0.2.1

data/lib/basecamp/services/todos_service.rb

@@ -0,0 +1,156 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for todo operations.
+    #
+    # @example List todos in a todolist
+    #   account.todos.list(project_id: 123, todolist_id: 456).each do |todo|
+    #     puts "#{todo["content"]} (#{todo["completed"] ? "done" : "pending"})"
+    #   end
+    #
+    # @example Create a todo
+    #   todo = account.todos.create(
+    #     project_id: 123,
+    #     todolist_id: 456,
+    #     content: "Write documentation",
+    #     assignee_ids: [789]
+    #   )
+    #
+    # @example Complete a todo
+    #   account.todos.complete(project_id: 123, todo_id: 456)
+    class TodosService < BaseService
+      # Lists todos in a todolist.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todolist_id [Integer, String] todolist ID
+      # @param status [String, nil] filter by status ("archived", "trashed")
+      # @param completed [Boolean, nil] filter by completion status
+      # @return [Enumerator<Hash>] todos
+      def list(project_id:, todolist_id:, status: nil, completed: nil)
+        params = compact_params(status: status, completed: completed)
+        paginate(bucket_path(project_id, "/todolists/#{todolist_id}/todos.json"), params: params)
+      end
+
+      # Gets a specific todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @return [Hash] todo data
+      def get(project_id:, todo_id:)
+        http_get(bucket_path(project_id, "/todos/#{todo_id}.json")).json
+      end
+
+      # Creates a new todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todolist_id [Integer, String] todolist ID
+      # @param content [String] todo content (can include HTML)
+      # @param description [String, nil] extended description (HTML)
+      # @param assignee_ids [Array<Integer>, nil] user IDs to assign
+      # @param completion_subscriber_ids [Array<Integer>, nil] user IDs to notify on completion
+      # @param notify [Boolean] whether to notify assignees
+      # @param due_on [String, nil] due date (YYYY-MM-DD)
+      # @param starts_on [String, nil] start date (YYYY-MM-DD)
+      # @return [Hash] created todo
+      def create(
+        project_id:,
+        todolist_id:,
+        content:,
+        description: nil,
+        assignee_ids: nil,
+        completion_subscriber_ids: nil,
+        notify: true,
+        due_on: nil,
+        starts_on: nil
+      )
+        body = compact_params(
+          content: content,
+          description: description,
+          assignee_ids: assignee_ids,
+          completion_subscriber_ids: completion_subscriber_ids,
+          notify: notify,
+          due_on: due_on,
+          starts_on: starts_on
+        )
+        http_post(bucket_path(project_id, "/todolists/#{todolist_id}/todos.json"), body: body).json
+      end
+
+      # Updates a todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @param content [String, nil] new content
+      # @param description [String, nil] new description
+      # @param assignee_ids [Array<Integer>, nil] new assignee IDs
+      # @param completion_subscriber_ids [Array<Integer>, nil] new completion subscriber IDs
+      # @param notify [Boolean, nil] whether to notify
+      # @param due_on [String, nil] new due date
+      # @param starts_on [String, nil] new start date
+      # @return [Hash] updated todo
+      def update(
+        project_id:,
+        todo_id:,
+        content: nil,
+        description: nil,
+        assignee_ids: nil,
+        completion_subscriber_ids: nil,
+        notify: nil,
+        due_on: nil,
+        starts_on: nil
+      )
+        body = compact_params(
+          content: content,
+          description: description,
+          assignee_ids: assignee_ids,
+          completion_subscriber_ids: completion_subscriber_ids,
+          notify: notify,
+          due_on: due_on,
+          starts_on: starts_on
+        )
+        http_put(bucket_path(project_id, "/todos/#{todo_id}.json"), body: body).json
+      end
+
+      # Completes a todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @return [void]
+      def complete(project_id:, todo_id:)
+        http_post(bucket_path(project_id, "/todos/#{todo_id}/completion.json"))
+        nil
+      end
+
+      # Uncompletes a todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @return [void]
+      def uncomplete(project_id:, todo_id:)
+        http_delete(bucket_path(project_id, "/todos/#{todo_id}/completion.json"))
+        nil
+      end
+
+      # Repositions a todo within its todolist.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @param position [Integer] new position (1-based)
+      # @return [void]
+      def reposition(project_id:, todo_id:, position:)
+        http_put(bucket_path(project_id, "/todos/#{todo_id}/position.json"), body: { position: position })
+        nil
+      end
+
+      # Trashes a todo.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todo_id [Integer, String] todo ID
+      # @return [void]
+      def trash(project_id:, todo_id:)
+        http_delete(bucket_path(project_id, "/todos/#{todo_id}.json"))
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/todosets_service.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for todoset operations.
+    #
+    # Each project has one todoset which is the container for all todolists.
+    #
+    # @example Get a todoset
+    #   todoset = account.todosets.get(project_id: 123, todoset_id: 456)
+    #   puts "#{todoset["name"]} - #{todoset["todolists_count"]} lists"
+    class TodosetsService < BaseService
+      # Gets a specific todoset.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param todoset_id [Integer, String] todoset ID
+      # @return [Hash] todoset data
+      def get(project_id:, todoset_id:)
+        http_get(bucket_path(project_id, "/todosets/#{todoset_id}")).json
+      end
+    end
+  end
+end

data/lib/basecamp/services/tools_service.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for dock tool operations.
+    #
+    # Tools are dock items in a Basecamp project (e.g., Message Board,
+    # Todos, Schedule, etc.). This service allows you to manage these tools.
+    #
+    # @example Get a tool
+    #   tool = account.tools.get(project_id: 123, tool_id: 456)
+    #   puts "#{tool["name"]} - #{tool["enabled"] ? "enabled" : "disabled"}"
+    #
+    # @example Enable and reposition a tool
+    #   account.tools.enable(project_id: 123, tool_id: 456)
+    #   account.tools.reposition(project_id: 123, tool_id: 456, position: 1)
+    class ToolsService < BaseService
+      # Gets a tool by ID.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @return [Hash] tool data
+      def get(project_id:, tool_id:)
+        http_get(bucket_path(project_id, "/dock/tools/#{tool_id}")).json
+      end
+
+      # Clones an existing tool to create a new one.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param source_tool_id [Integer, String] ID of the tool to clone
+      # @return [Hash] newly created tool
+      def clone(project_id:, source_tool_id:)
+        http_post(bucket_path(project_id, "/dock/tools/#{source_tool_id}/clone.json")).json
+      end
+
+      # Updates (renames) an existing tool.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @param title [String] new title for the tool
+      # @return [Hash] updated tool
+      def update(project_id:, tool_id:, title:)
+        http_put(bucket_path(project_id, "/dock/tools/#{tool_id}"), body: { title: title }).json
+      end
+
+      # Deletes a tool (moves it to trash).
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @return [void]
+      def delete(project_id:, tool_id:)
+        http_delete(bucket_path(project_id, "/dock/tools/#{tool_id}"))
+        nil
+      end
+
+      # Enables a tool (shows it on the project dock).
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @return [void]
+      def enable(project_id:, tool_id:)
+        http_post(bucket_path(project_id, "/dock/tools/#{tool_id}/position.json"))
+        nil
+      end
+
+      # Disables a tool (hides it from the project dock).
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @return [void]
+      def disable(project_id:, tool_id:)
+        http_delete(bucket_path(project_id, "/dock/tools/#{tool_id}/position.json"))
+        nil
+      end
+
+      # Changes the position of a tool on the project dock.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param tool_id [Integer, String] tool ID
+      # @param position [Integer] new position (1-based, 1 = first on dock)
+      # @return [void]
+      def reposition(project_id:, tool_id:, position:)
+        http_put(bucket_path(project_id, "/dock/tools/#{tool_id}/position.json"),
+                 body: { position: position })
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/uploads_service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for upload operations.
+    #
+    # Uploads are files stored within vaults. They are created from
+    # attachments (via attachable_sgid) and can have descriptions
+    # and version history.
+    #
+    # @example List uploads in a vault
+    #   account.uploads.list(project_id: 123, vault_id: 456).each do |upload|
+    #     puts "#{upload["filename"]} - #{upload["byte_size"]} bytes"
+    #   end
+    #
+    # @example Create an upload
+    #   upload = account.uploads.create(
+    #     project_id: 123,
+    #     vault_id: 456,
+    #     attachable_sgid: attachment_sgid,
+    #     description: "Q4 financial report"
+    #   )
+    class UploadsService < BaseService
+      # Lists all uploads in a vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @return [Enumerator<Hash>] uploads
+      def list(project_id:, vault_id:)
+        paginate(bucket_path(project_id, "/vaults/#{vault_id}/uploads.json"))
+      end
+
+      # Gets a specific upload.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param upload_id [Integer, String] upload ID
+      # @return [Hash] upload data
+      def get(project_id:, upload_id:)
+        http_get(bucket_path(project_id, "/uploads/#{upload_id}")).json
+      end
+
+      # Creates a new upload in a vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @param attachable_sgid [String] signed global ID from attachment upload
+      # @param description [String, nil] upload description in HTML
+      # @param base_name [String, nil] filename without extension
+      # @return [Hash] created upload
+      def create(project_id:, vault_id:, attachable_sgid:, description: nil, base_name: nil)
+        body = compact_params(
+          attachable_sgid: attachable_sgid,
+          description: description,
+          base_name: base_name
+        )
+        http_post(bucket_path(project_id, "/vaults/#{vault_id}/uploads.json"), body: body).json
+      end
+
+      # Updates an existing upload.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param upload_id [Integer, String] upload ID
+      # @param description [String, nil] new description
+      # @param base_name [String, nil] new filename without extension
+      # @return [Hash] updated upload
+      def update(project_id:, upload_id:, description: nil, base_name: nil)
+        body = compact_params(
+          description: description,
+          base_name: base_name
+        )
+        http_put(bucket_path(project_id, "/uploads/#{upload_id}"), body: body).json
+      end
+
+      # Lists all versions of an upload.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param upload_id [Integer, String] upload ID
+      # @return [Enumerator<Hash>] upload versions
+      def list_versions(project_id:, upload_id:)
+        paginate(bucket_path(project_id, "/uploads/#{upload_id}/versions.json"))
+      end
+    end
+  end
+end

data/lib/basecamp/services/vaults_service.rb

@@ -0,0 +1,84 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for vault (folder) operations.
+    #
+    # Vaults are folders in the Files & Documents tool. They can contain
+    # documents, uploads (files), and nested vaults (subfolders).
+    #
+    # @example Get a vault
+    #   vault = account.vaults.get(project_id: 123, vault_id: 456)
+    #
+    # @example List subfolders
+    #   account.vaults.list(project_id: 123, vault_id: 456).each do |folder|
+    #     puts folder["title"]
+    #   end
+    #
+    # @example Create a subfolder
+    #   vault = account.vaults.create(
+    #     project_id: 123,
+    #     vault_id: 456,
+    #     title: "2024 Reports"
+    #   )
+    class VaultsService < BaseService
+      # Gets a specific vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @return [Hash] vault data
+      def get(project_id:, vault_id:)
+        http_get(bucket_path(project_id, "/vaults/#{vault_id}")).json
+      end
+
+      # Lists all child vaults (subfolders) in a vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] parent vault ID
+      # @return [Enumerator<Hash>] child vaults
+      def list(project_id:, vault_id:)
+        paginate(bucket_path(project_id, "/vaults/#{vault_id}/vaults.json"))
+      end
+
+      # Creates a new child vault (subfolder).
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] parent vault ID
+      # @param title [String] vault name
+      # @return [Hash] created vault
+      def create(project_id:, vault_id:, title:)
+        body = { title: title }
+        http_post(bucket_path(project_id, "/vaults/#{vault_id}/vaults.json"), body: body).json
+      end
+
+      # Updates an existing vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @param title [String, nil] new title
+      # @return [Hash] updated vault
+      def update(project_id:, vault_id:, title: nil)
+        body = compact_params(title: title)
+        http_put(bucket_path(project_id, "/vaults/#{vault_id}"), body: body).json
+      end
+
+      # Lists all documents in a vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @return [Enumerator<Hash>] documents
+      def list_documents(project_id:, vault_id:)
+        paginate(bucket_path(project_id, "/vaults/#{vault_id}/documents.json"))
+      end
+
+      # Lists all uploads (files) in a vault.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param vault_id [Integer, String] vault ID
+      # @return [Enumerator<Hash>] uploads
+      def list_uploads(project_id:, vault_id:)
+        paginate(bucket_path(project_id, "/vaults/#{vault_id}/uploads.json"))
+      end
+    end
+  end
+end

data/lib/basecamp/services/webhooks_service.rb

@@ -0,0 +1,88 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for webhook operations.
+    #
+    # Webhooks allow external services to receive notifications when events
+    # occur in a Basecamp project.
+    #
+    # @example List webhooks
+    #   account.webhooks.list(project_id: 123).each do |webhook|
+    #     puts "#{webhook["payload_url"]} - #{webhook["active"]}"
+    #   end
+    #
+    # @example Create a webhook
+    #   webhook = account.webhooks.create(
+    #     project_id: 123,
+    #     payload_url: "https://example.com/webhooks/basecamp",
+    #     types: ["Todo", "Message"]
+    #   )
+    class WebhooksService < BaseService
+      # Lists all webhooks in a project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @return [Enumerator<Hash>] webhooks
+      def list(project_id:)
+        paginate(bucket_path(project_id, "/webhooks.json"))
+      end
+
+      # Gets a specific webhook.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param webhook_id [Integer, String] webhook ID
+      # @return [Hash] webhook data
+      def get(project_id:, webhook_id:)
+        http_get(bucket_path(project_id, "/webhooks/#{webhook_id}")).json
+      end
+
+      # Creates a new webhook.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param payload_url [String] URL to receive webhook payloads
+      # @param types [Array<String>, nil] recording types to subscribe to
+      # @return [Hash] created webhook
+      def create(project_id:, payload_url:, types: nil)
+        raise Basecamp::UsageError.new("Webhook payload URL is required") if payload_url.to_s.empty?
+        Basecamp::Security.require_https!(payload_url, "webhook payload URL")
+
+        body = compact_params(
+          payload_url: payload_url,
+          types: types
+        )
+        http_post(bucket_path(project_id, "/webhooks.json"), body: body).json
+      end
+
+      # Updates an existing webhook.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param webhook_id [Integer, String] webhook ID
+      # @param payload_url [String, nil] new URL
+      # @param types [Array<String>, nil] new recording types
+      # @param active [Boolean, nil] whether the webhook is active
+      # @return [Hash] updated webhook
+      def update(project_id:, webhook_id:, payload_url: nil, types: nil, active: nil)
+        if payload_url
+          Basecamp::Security.require_https!(payload_url, "webhook payload URL")
+        end
+
+        body = compact_params(
+          payload_url: payload_url,
+          types: types,
+          active: active
+        )
+        http_put(bucket_path(project_id, "/webhooks/#{webhook_id}"), body: body).json
+      end
+
+      # Deletes a webhook.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param webhook_id [Integer, String] webhook ID
+      # @return [void]
+      def delete(project_id:, webhook_id:)
+        http_delete(bucket_path(project_id, "/webhooks/#{webhook_id}"))
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/static_token_provider.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # A simple token provider that returns a static access token.
+  # Useful for testing or when you manage token refresh externally.
+  #
+  # @example
+  #   provider = Basecamp::StaticTokenProvider.new(ENV["BASECAMP_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/basecamp/token_provider.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Interface for providing OAuth access tokens.
+  # Implement this to provide custom token management (e.g., refresh tokens).
+  #
+  # @example Static token provider
+  #   token_provider = Basecamp::StaticTokenProvider.new("your-access-token")
+  #   client = Basecamp::Client.new(config: config, token_provider: token_provider)
+  #
+  # @example Custom token provider with refresh
+  #   class MyTokenProvider
+  #     include Basecamp::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 OAuth 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/basecamp/version.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+module Basecamp
+  VERSION = "0.2.1"
+  API_VERSION = "2026-01-26"
+end

data/lib/basecamp/webhooks/event.rb

@@ -0,0 +1,52 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Webhooks
+    # Structured wrapper around webhook event payloads.
+    # Accepts any hash - does not reject unknown fields or event kinds.
+    class Event
+      attr_reader :id, :kind, :details, :created_at, :recording, :creator, :copy, :raw
+
+      def initialize(hash)
+        @raw = hash
+        @id = hash["id"]
+        @kind = hash["kind"]
+        @details = hash["details"] || {}
+        @created_at = hash["created_at"]
+        @recording = hash["recording"] || {}
+        @creator = hash["creator"] || {}
+        @copy = hash["copy"]
+      end
+
+      # Parse "todo_created" -> { type: "todo", action: "created" }
+      def parsed_kind
+        return { type: kind, action: "" } unless kind&.include?("_")
+        last_underscore = kind.rindex("_")
+        {
+          type: kind[0...last_underscore],
+          action: kind[(last_underscore + 1)..]
+        }
+      end
+    end
+
+    # Known webhook recording types (convenience constants, not exhaustive).
+    module RecordingType
+      CHECKIN_REPLY = "Checkin::Reply"
+      CLOUD_FILE = "CloudFile"
+      COMMENT = "Comment"
+      DOCUMENT = "Document"
+      FORWARD_REPLY = "Forward::Reply"
+      GOOGLE_DOCUMENT = "GoogleDocument"
+      INBOX_FORWARD = "Inbox::Forward"
+      MESSAGE = "Message"
+      QUESTION = "Question"
+      QUESTION_ANSWER = "Question::Answer"
+      SCHEDULE_ENTRY = "Schedule::Entry"
+      TODO = "Todo"
+      TODOLIST = "Todolist"
+      TODOLIST_GROUP = "Todolist::Group"
+      UPLOAD = "Upload"
+      VAULT = "Vault"
+    end
+  end
+end