basecamp-sdk 0.2.1

data/lib/basecamp/services/lineup_service.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for lineup operations.
+    #
+    # The Lineup is Basecamp's visual timeline tool for tracking
+    # project schedules and milestones.
+    #
+    # @example Create a marker
+    #   marker = account.lineup.create_marker(
+    #     title: "Launch Day",
+    #     starts_on: "2024-03-01",
+    #     ends_on: "2024-03-01",
+    #     color: "green"
+    #   )
+    class LineupService < BaseService
+      # Creates a new marker on the lineup.
+      #
+      # @param title [String] marker title
+      # @param starts_on [String] start date (YYYY-MM-DD)
+      # @param ends_on [String] end date (YYYY-MM-DD)
+      # @param color [String, nil] marker color (white, red, orange, yellow, green, blue, aqua, purple, gray, pink, brown)
+      # @param description [String, nil] description in HTML
+      # @return [Hash] created marker
+      def create_marker(title:, starts_on:, ends_on:, color: nil, description: nil)
+        body = compact_params(
+          title: title,
+          starts_on: starts_on,
+          ends_on: ends_on,
+          color: color,
+          description: description
+        )
+        http_post("/lineup/markers.json", body: body).json
+      end
+
+      # Updates an existing marker.
+      #
+      # @param marker_id [Integer, String] marker ID
+      # @param title [String, nil] new title
+      # @param starts_on [String, nil] new start date (YYYY-MM-DD)
+      # @param ends_on [String, nil] new end date (YYYY-MM-DD)
+      # @param color [String, nil] new color
+      # @param description [String, nil] new description
+      # @return [Hash] updated marker
+      def update_marker(marker_id:, title: nil, starts_on: nil, ends_on: nil, color: nil, description: nil)
+        body = compact_params(
+          title: title,
+          starts_on: starts_on,
+          ends_on: ends_on,
+          color: color,
+          description: description
+        )
+        http_put("/lineup/markers/#{marker_id}", body: body).json
+      end
+
+      # Deletes a marker.
+      #
+      # @param marker_id [Integer, String] marker ID
+      # @return [void]
+      def delete_marker(marker_id:)
+        http_delete("/lineup/markers/#{marker_id}")
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/message_boards_service.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for message board operations.
+    #
+    # Each project has a message board where team members can post messages
+    # (announcements, updates, etc.).
+    #
+    # @example Get a message board
+    #   board = account.message_boards.get(project_id: 123, board_id: 456)
+    #   puts "#{board["title"]} - #{board["messages_count"]} messages"
+    class MessageBoardsService < BaseService
+      # Gets a specific message board.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param board_id [Integer, String] message board ID
+      # @return [Hash] message board data
+      def get(project_id:, board_id:)
+        http_get(bucket_path(project_id, "/message_boards/#{board_id}")).json
+      end
+    end
+  end
+end

data/lib/basecamp/services/message_types_service.rb

@@ -0,0 +1,79 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for message type (category) operations.
+    #
+    # Message types (also called categories) are used to categorize messages
+    # on a message board. Each message type has a name and icon.
+    #
+    # @example List message types
+    #   account.message_types.list(project_id: 123).each do |type|
+    #     puts "#{type["icon"]} #{type["name"]}"
+    #   end
+    #
+    # @example Create a message type
+    #   type = account.message_types.create(
+    #     project_id: 123,
+    #     name: "Announcement",
+    #     icon: "📢"
+    #   )
+    class MessageTypesService < BaseService
+      # Lists all message types in a project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @return [Enumerator<Hash>] message types
+      def list(project_id:)
+        paginate(bucket_path(project_id, "/categories.json"))
+      end
+
+      # Gets a message type by ID.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param type_id [Integer, String] message type ID
+      # @return [Hash] message type data
+      def get(project_id:, type_id:)
+        http_get(bucket_path(project_id, "/categories/#{type_id}")).json
+      end
+
+      # Creates a new message type in a project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param name [String] message type name
+      # @param icon [String] message type icon
+      # @return [Hash] created message type
+      def create(project_id:, name:, icon:)
+        body = {
+          name: name,
+          icon: icon
+        }
+        http_post(bucket_path(project_id, "/categories.json"), body: body).json
+      end
+
+      # Updates an existing message type.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param type_id [Integer, String] message type ID
+      # @param name [String, nil] new name
+      # @param icon [String, nil] new icon
+      # @return [Hash] updated message type
+      def update(project_id:, type_id:, name: nil, icon: nil)
+        body = compact_params(
+          name: name,
+          icon: icon
+        )
+        http_put(bucket_path(project_id, "/categories/#{type_id}"), body: body).json
+      end
+
+      # Deletes a message type from a project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param type_id [Integer, String] message type ID
+      # @return [void]
+      def delete(project_id:, type_id:)
+        http_delete(bucket_path(project_id, "/categories/#{type_id}"))
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/messages_service.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for message operations.
+    #
+    # Messages are posts on a project's message board. They have a subject,
+    # content, and can be categorized with message types.
+    #
+    # @example List messages
+    #   account.messages.list(project_id: 123, board_id: 456).each do |message|
+    #     puts "#{message["subject"]} by #{message["creator"]["name"]}"
+    #   end
+    #
+    # @example Create a message
+    #   message = account.messages.create(
+    #     project_id: 123,
+    #     board_id: 456,
+    #     subject: "Project Update",
+    #     content: "<p>Here's what happened this week...</p>"
+    #   )
+    #
+    # @example Pin a message
+    #   account.messages.pin(project_id: 123, message_id: 789)
+    class MessagesService < BaseService
+      # Lists all messages on a message board.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param board_id [Integer, String] message board ID
+      # @return [Enumerator<Hash>] messages
+      def list(project_id:, board_id:)
+        paginate(bucket_path(project_id, "/message_boards/#{board_id}/messages.json"))
+      end
+
+      # Gets a specific message.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [Hash] message data
+      def get(project_id:, message_id:)
+        http_get(bucket_path(project_id, "/messages/#{message_id}")).json
+      end
+
+      # Creates a new message on a message board.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param board_id [Integer, String] message board ID
+      # @param subject [String] message title
+      # @param content [String, nil] message body in HTML
+      # @param status [String, nil] "drafted" or "active" (defaults to active)
+      # @param category_id [Integer, nil] message type ID
+      # @return [Hash] created message
+      def create(project_id:, board_id:, subject:, content: nil, status: nil, category_id: nil)
+        body = compact_params(
+          subject: subject,
+          content: content,
+          status: status,
+          category_id: category_id
+        )
+        http_post(bucket_path(project_id, "/message_boards/#{board_id}/messages.json"), body: body).json
+      end
+
+      # Updates an existing message.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @param subject [String, nil] new title
+      # @param content [String, nil] new content in HTML
+      # @param status [String, nil] "drafted" or "active"
+      # @param category_id [Integer, nil] message type ID
+      # @return [Hash] updated message
+      def update(project_id:, message_id:, subject: nil, content: nil, status: nil, category_id: nil)
+        body = compact_params(
+          subject: subject,
+          content: content,
+          status: status,
+          category_id: category_id
+        )
+        http_put(bucket_path(project_id, "/messages/#{message_id}"), body: body).json
+      end
+
+      # Pins a message to the top of the message board.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [void]
+      def pin(project_id:, message_id:)
+        http_post(bucket_path(project_id, "/recordings/#{message_id}/pin.json"))
+        nil
+      end
+
+      # Unpins a message from the top of the message board.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [void]
+      def unpin(project_id:, message_id:)
+        http_delete(bucket_path(project_id, "/recordings/#{message_id}/pin.json"))
+        nil
+      end
+
+      # Archives a message.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [void]
+      def archive(project_id:, message_id:)
+        http_put(bucket_path(project_id, "/recordings/#{message_id}/status/archived.json"))
+        nil
+      end
+
+      # Restores an archived message to active status.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [void]
+      def unarchive(project_id:, message_id:)
+        http_put(bucket_path(project_id, "/recordings/#{message_id}/status/active.json"))
+        nil
+      end
+
+      # Moves a message to the trash.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param message_id [Integer, String] message ID
+      # @return [void]
+      def trash(project_id:, message_id:)
+        http_put(bucket_path(project_id, "/recordings/#{message_id}/status/trashed.json"))
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/people_service.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for people operations.
+    #
+    # People are the users in your Basecamp account.
+    #
+    # @example List all people
+    #   account.people.list.each do |person|
+    #     puts "#{person["name"]} <#{person["email_address"]}>"
+    #   end
+    #
+    # @example Get current user's profile
+    #   me = account.people.me
+    #   puts "Logged in as #{me["name"]}"
+    class PeopleService < BaseService
+      # Lists all people in the account.
+      #
+      # @return [Enumerator<Hash>] people
+      def list
+        paginate("/people.json")
+      end
+
+      # Gets a specific person.
+      #
+      # @param person_id [Integer, String] person ID
+      # @return [Hash] person data
+      def get(person_id:)
+        http_get("/people/#{person_id}").json
+      end
+
+      # Gets the current user's profile.
+      #
+      # @return [Hash] current user's profile
+      def me
+        http_get("/my/profile.json").json
+      end
+
+      # Lists all people who can be pinged (mentioned).
+      #
+      # @return [Enumerator<Hash>] pingable people
+      def list_pingable
+        paginate("/circles/people.json")
+      end
+
+      # Lists all people in a project.
+      #
+      # @param project_id [Integer, String] project ID
+      # @return [Enumerator<Hash>] project members
+      def list_project_people(project_id:)
+        paginate("/projects/#{project_id}/people.json")
+      end
+
+      # Updates project access for users.
+      #
+      # @param project_id [Integer, String] project ID
+      # @param grant [Array<Integer>, nil] user IDs to grant access
+      # @param revoke [Array<Integer>, nil] user IDs to revoke access
+      # @param create [Array<Hash>, nil] new users to create and grant access
+      # @return [void]
+      def update_project_access(project_id:, grant: nil, revoke: nil, create: nil)
+        body = compact_params(
+          grant: grant,
+          revoke: revoke,
+          create: create
+        )
+        http_put("/projects/#{project_id}/people/users.json", body: body)
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/projects_service.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for project (Basecamp) operations.
+    #
+    # @example List all projects
+    #   account.projects.list.each do |project|
+    #     puts "#{project["name"]} (#{project["id"]})"
+    #   end
+    #
+    # @example Get a specific project
+    #   project = account.projects.get(123)
+    #   puts project["name"]
+    #
+    # @example Create a project
+    #   project = account.projects.create(name: "My Project", description: "A new project")
+    class ProjectsService < BaseService
+      # Lists all projects in the account.
+      #
+      # @param status [String, nil] filter by status ("active", "archived", "trashed")
+      # @return [Enumerator<Hash>] projects
+      def list(status: nil)
+        params = compact_params(status: status)
+        paginate("/projects.json", params: params)
+      end
+
+      # Gets a specific project.
+      #
+      # @param project_id [Integer, String] project ID
+      # @return [Hash] project data
+      def get(project_id)
+        http_get("/projects/#{project_id}.json").json
+      end
+
+      # Creates a new project.
+      #
+      # @param name [String] project name
+      # @param description [String, nil] project description
+      # @return [Hash] created project
+      def create(name:, description: nil)
+        body = compact_params(name: name, description: description)
+        http_post("/projects.json", body: body).json
+      end
+
+      # Updates a project.
+      #
+      # @param project_id [Integer, String] project ID
+      # @param name [String, nil] new name
+      # @param description [String, nil] new description
+      # @return [Hash] updated project
+      def update(project_id, name: nil, description: nil)
+        body = compact_params(name: name, description: description)
+        http_put("/projects/#{project_id}.json", body: body).json
+      end
+
+      # Trashes a project.
+      #
+      # @param project_id [Integer, String] project ID
+      # @return [void]
+      def trash(project_id)
+        http_delete("/projects/#{project_id}.json")
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/recordings_service.rb

@@ -0,0 +1,127 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for recording operations.
+    #
+    # Recordings are the base type for most content in Basecamp, including
+    # todos, messages, comments, documents, uploads, etc. This service
+    # provides common operations that work across all recording types.
+    #
+    # @example List all recordings in a project
+    #   account.recordings.list(type: "Todo", bucket: 123).each do |recording|
+    #     puts "#{recording["title"]} - #{recording["status"]}"
+    #   end
+    #
+    # @example Archive a recording
+    #   account.recordings.archive(project_id: 123, recording_id: 456)
+    class RecordingsService < BaseService
+      # Lists recordings across projects.
+      #
+      # @param type [String] recording type (e.g., "Todo", "Message", "Comment")
+      # @param bucket [Integer, nil] filter by project ID
+      # @param status [String, nil] filter by status ("active", "archived", "trashed")
+      # @param sort [String, nil] sort field ("created_at", "updated_at")
+      # @param direction [String, nil] sort direction ("asc", "desc")
+      # @return [Enumerator<Hash>] recordings
+      def list(type:, bucket: nil, status: nil, sort: nil, direction: nil)
+        params = compact_params(
+          type: type,
+          bucket: bucket,
+          status: status,
+          sort: sort,
+          direction: direction
+        )
+        paginate("/projects/recordings.json", params: params)
+      end
+
+      # Gets a specific recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [Hash] recording data
+      def get(project_id:, recording_id:)
+        http_get(bucket_path(project_id, "/recordings/#{recording_id}")).json
+      end
+
+      # Archives a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [void]
+      def archive(project_id:, recording_id:)
+        http_put(bucket_path(project_id, "/recordings/#{recording_id}/status/archived.json"))
+        nil
+      end
+
+      # Unarchives a recording (restores to active).
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [void]
+      def unarchive(project_id:, recording_id:)
+        http_put(bucket_path(project_id, "/recordings/#{recording_id}/status/active.json"))
+        nil
+      end
+
+      # Moves a recording to the trash.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [void]
+      def trash(project_id:, recording_id:)
+        http_put(bucket_path(project_id, "/recordings/#{recording_id}/status/trashed.json"))
+        nil
+      end
+
+      # Lists events (change history) for a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [Enumerator<Hash>] events
+      def list_events(project_id:, recording_id:)
+        paginate(bucket_path(project_id, "/recordings/#{recording_id}/events.json"))
+      end
+
+      # Gets the subscription status for a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [Hash] subscription data
+      def get_subscription(project_id:, recording_id:)
+        http_get(bucket_path(project_id, "/recordings/#{recording_id}/subscription.json")).json
+      end
+
+      # Subscribes to a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [Hash] subscription data
+      def subscribe(project_id:, recording_id:)
+        http_post(bucket_path(project_id, "/recordings/#{recording_id}/subscription.json")).json
+      end
+
+      # Unsubscribes from a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @return [void]
+      def unsubscribe(project_id:, recording_id:)
+        http_delete(bucket_path(project_id, "/recordings/#{recording_id}/subscription.json"))
+        nil
+      end
+
+      # Sets client visibility for a recording.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID
+      # @param visible [Boolean] whether clients can see this recording
+      # @return [void]
+      def set_client_visibility(project_id:, recording_id:, visible:)
+        http_put(bucket_path(project_id, "/recordings/#{recording_id}/client_visibility.json"),
+                 body: { visible: visible })
+        nil
+      end
+    end
+  end
+end

data/lib/basecamp/services/reports_service.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for report operations.
+    #
+    # Provides access to various report types including timesheet and assigned todos reports.
+    #
+    # @example Get account-wide timesheet
+    #   result = account.reports.timesheet
+    #   result["entries"].each { |e| puts e["hours"] }
+    #
+    # @example Get list of people with assigned todos
+    #   people = account.reports.assignable_people.to_a
+    #
+    # @example Get todos assigned to a specific person
+    #   result = account.reports.assigned_todos(person_id: 123)
+    #   result["todos"].each { |todo| puts todo["content"] }
+    class ReportsService < BaseService
+      # Returns the account-wide timesheet report.
+      # This includes time entries across all projects in the account.
+      #
+      # @param from [String, nil] filter entries on or after this date (ISO 8601)
+      # @param to [String, nil] filter entries on or before this date (ISO 8601)
+      # @param person_id [Integer, nil] filter entries by a specific person
+      # @return [Hash] timesheet report object with "entries" array
+      def timesheet(from: nil, to: nil, person_id: nil)
+        params = compact_params(from: from, to: to, person_id: person_id)
+        response = http_get("/reports/timesheet.json", params: params)
+        response.json
+      end
+
+      # Returns the timesheet report for a specific project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param from [String, nil] filter entries on or after this date (ISO 8601)
+      # @param to [String, nil] filter entries on or before this date (ISO 8601)
+      # @param person_id [Integer, nil] filter entries by a specific person
+      # @return [Hash] timesheet report object with "entries" array
+      def project_timesheet(project_id:, from: nil, to: nil, person_id: nil)
+        params = compact_params(from: from, to: to, person_id: person_id)
+        response = http_get(bucket_path(project_id, "/timesheet.json"), params: params)
+        response.json
+      end
+
+      # Returns the timesheet report for a specific recording within a project.
+      #
+      # @param project_id [Integer, String] project (bucket) ID
+      # @param recording_id [Integer, String] recording ID (e.g., a todo or message)
+      # @param from [String, nil] filter entries on or after this date (ISO 8601)
+      # @param to [String, nil] filter entries on or before this date (ISO 8601)
+      # @param person_id [Integer, nil] filter entries by a specific person
+      # @return [Hash] timesheet report object with "entries" array
+      def recording_timesheet(project_id:, recording_id:, from: nil, to: nil, person_id: nil)
+        params = compact_params(from: from, to: to, person_id: person_id)
+        response = http_get(bucket_path(project_id, "/recordings/#{recording_id}/timesheet.json"), params: params)
+        response.json
+      end
+
+      # Returns the list of people who have assigned todos.
+      # Use assigned_todos(person_id:) to get the actual todos for a specific person.
+      #
+      # @return [Enumerator<Hash>] list of Person objects
+      def assignable_people
+        paginate("/reports/todos/assigned.json")
+      end
+
+      # Returns all todos assigned to a specific person.
+      #
+      # @param person_id [Integer, String] person ID
+      # @param group_by [String, nil] grouping method: "bucket" or "date"
+      # @return [Hash] object with "person", "grouped_by", and "todos" keys
+      def assigned_todos(person_id:, group_by: nil)
+        params = compact_params(group_by: group_by)
+        response = http_get("/reports/todos/assigned/#{person_id}", params: params)
+        response.json
+      end
+    end
+  end
+end