basecamp-sdk 0.14.0 → 0.16.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9b770f1606323f83fb028ebb44d51e0d2500664a6d88ec9209dc227807ace197
-  data.tar.gz: 418cf25fbdc65f25db5e9d816565cd20a7f2e3d0c06c5a147dcf896c38d2ec9e
+  metadata.gz: 67cf91504a5aadff973463d83b4a4de98aa4ad35e2dd7d0d4e5f4f26021e8423
+  data.tar.gz: 88eacbb6628831a01e6a9cb56503618377ffec4a85ad85d5a514b025ff53dd2a
 SHA512:
-  metadata.gz: 82caf3dad37f93e3b9ce65ad2da90b798efa466d0a2fc8e25d63ea84778357a436fe0da8615bbde3f03c3836eb9077dee20b35775ab283900437e575a64aa99e
-  data.tar.gz: c17f87a5bac84d66e89edf3725fb3321fa768b31d868d8214f1dbf8326a6361f73dd5acf355c4a22712a9434fe5514d0b750edd2eb8d6ce15468a0867f44419d
+  metadata.gz: 8cede9f49e112c50b65d7c7c4901f442cba400211bfe4676a9af95a95ac4ca5da1a1477c529f72456745a0f8423b766162c151135b89a2c52ce1abbacb9eb17f
+  data.tar.gz: 695198c7697799719f0d66657463ed8ad76739bcd3bbe11877ad0a16d1fdd6b20602e2d6efa623c9d6e05a2b78ef5528e346ebec5975dd1697e5379e96b1e640

data/README.md

@@ -316,7 +316,7 @@ aborts before an oversized body is buffered.
 
 ## Services
 
-The SDK provides 46 account-scoped services. The table below covers the common ones; see `lib/basecamp/generated/services/` for the authoritative, complete set:
+The SDK provides the full account-scoped service set documented in SPEC §5. The table below covers the common ones; see `lib/basecamp/generated/services/` for the authoritative, complete set:
 
 | Service | Description |
 |---------|-------------|

data/lib/basecamp/api_error.rb

@@ -17,11 +17,12 @@ module Basecamp
     # Creates an ApiError from an HTTP status code.
     # @param status [Integer] HTTP status code
     # @param message [String, nil] optional error message
+    # @param hint [String, nil] optional hint (SPEC section 6 step 3)
     # @return [ApiError]
-    def self.from_status(status, message = nil)
+    def self.from_status(status, message = nil, hint: nil)
       message ||= "Request failed (HTTP #{status})"
       retryable = status >= 500 && status < 600
-      new(message, http_status: status, retryable: retryable)
+      new(message, http_status: status, hint: hint, retryable: retryable)
     end
   end
 end

data/lib/basecamp/client.rb

@@ -240,7 +240,9 @@ module Basecamp
     #
     # Handles the full download flow: URL rewriting to the configured API host,
     # authenticated first hop (which typically 302s to a signed download URL),
-    # and unauthenticated second hop to fetch the actual file content.
+    # and unauthenticated second hop to fetch the actual file content. Neither
+    # hop follows a redirect on its own: hop 1's is the dispatch to hop 2, and
+    # a redirect on hop 2 is an error (SPEC §14 "Hop-2 Redirect Policy").
     #
     # @param raw_url [String] absolute download URL (e.g., from bc-attachment elements)
     # @return [DownloadResult] the download result with body, content_type, content_length, filename
@@ -505,6 +507,11 @@ module Basecamp
       service(:bookmarks) { Services::BookmarksService.new(self) }
     end
 
+    # @return [Services::BubbleUpsService]
+    def bubble_ups
+      service(:bubble_ups) { Services::BubbleUpsService.new(self) }
+    end
+
     # @return [Services::FoldersService]
     def folders
       service(:folders) { Services::FoldersService.new(self) }
@@ -616,7 +623,35 @@ module Basecamp
     end
 
     def fetch_signed_download(url)
-      uri = URI.parse(url)
+      # The Location target is server-supplied, and this unauthenticated hop
+      # has no same_origin? gate to refuse it (a signed URL is legitimately
+      # cross-origin), so illegible targets must be refused here — as
+      # ApiError, matching the legible refusals Go and TypeScript surface
+      # when their dial rejects the scheme. One predicate states the whole
+      # invariant — a dialable absolute HTTP(S) URL — because piecemeal
+      # guards kept leaking: "it parses" admitted "ftp://", and "scheme is
+      # http(s)" admitted hostless "http:foo", which Net::HTTP::Get rejects
+      # with a raw ArgumentError before the dial (nothing is ever sent).
+      # URI.parse types the scheme (URI::HTTPS < URI::HTTP), and a nil or
+      # empty host ("http:foo", "http:///x") is undialable.
+      uri = begin
+        URI.parse(url)
+      rescue URI::Error
+        nil
+      end
+      unless uri.is_a?(URI::HTTP) && uri.host && !uri.host.empty?
+        # SPEC §9: the signed URL is a credential — render its origin alone,
+        # projected from the parse, or the fixed token when no complete origin
+        # exists. Truncating the whole URL kept a short query intact.
+        origin = if uri&.scheme && uri&.host && !uri.host.empty?
+          port = uri.port && uri.port != uri.default_port ? ":#{uri.port}" : ""
+          "#{uri.scheme}://#{uri.host}#{port}"
+        else
+          "unparsable"
+        end
+        raise ApiError.new("redirect to undialable download URL: #{origin}")
+      end
+
       http_client = Net::HTTP.new(uri.host, uri.port)
       http_client.use_ssl = (uri.scheme == "https")
       http_client.open_timeout = config.timeout
@@ -625,9 +660,24 @@ module Basecamp
       request = Net::HTTP::Get.new(uri)
 
       begin
+        # Net::HTTP#request never follows a redirect, which is the policy:
+        # the signed URL is the one destination the API host named, and a
+        # redirect from it is refused below, not dialled (SPEC §14 "Hop-2
+        # Redirect Policy"). Stated here so a move to a following client
+        # (Faraday, Net::HTTP.get_response's callers) has to argue with it.
         response = http_client.request(request)
-      rescue StandardError => e
-        raise NetworkError.new("Download failed: #{e.message}", cause: e)
+      rescue StandardError
+        # SPEC §9: the transport error renders the signed URL, so neither its
+        # message nor the exception itself survives. cause: nil at the raise
+        # site — MRI sets the built-in cause at raise time past the class's
+        # stored cause: keyword (same pattern as oauth/exchange.rb).
+        raise NetworkError.new("Download failed"), cause: nil
+      end
+
+      # The exact set hop 1 dispatches on, not Net::HTTPRedirection — that
+      # class also covers 304, which is a cache answer, not a redirect.
+      if [ 301, 302, 303, 307, 308 ].include?(response.code.to_i)
+        raise ApiError.new("redirect #{response.code} on the signed download hop is not followed", http_status: response.code.to_i)
       end
 
       unless response.is_a?(Net::HTTPSuccess)

data/lib/basecamp/config.rb

@@ -35,7 +35,21 @@ module Basecamp
     attr_accessor :max_jitter
 
     # @return [Integer] maximum pages to fetch in paginated requests
-    attr_accessor :max_pages
+    attr_reader :max_pages
+
+    # A validating writer, not attr_accessor: Http reads the config live at
+    # every page boundary, so `config.max_pages = -1` after construction
+    # replaced the validated cap with a value validate! would have refused —
+    # the same second door TypeScript's compile-time-only `readonly` left
+    # open. The config deliberately stays mutable (from_file → load_from_env
+    # re-validation is builder-style by design); only the cap's invariant
+    # must hold at assignment.
+    #
+    # @param value [Integer] maximum pages to fetch in paginated requests
+    def max_pages=(value)
+      validate_max_pages!(value)
+      @max_pages = value
+    end
 
     # Default values
     DEFAULT_BASE_URL = "https://3.basecampapi.com"
@@ -164,7 +178,9 @@ module Basecamp
     # @param path [String] path to JSON config file
     # @return [Config]
     def self.from_file(path)
-      data = JSON.parse(File.read(path))
+      # UTF-8 regardless of process locale — JSON is UTF-8 (RFC 8259), and
+      # LC_ALL=C would otherwise read as US-ASCII.
+      data = JSON.parse(File.read(path, encoding: "UTF-8"))
       config = new(
         base_url: data["base_url"] || DEFAULT_BASE_URL,
         timeout: data["timeout"] || DEFAULT_TIMEOUT,
@@ -199,7 +215,13 @@ module Basecamp
     def validate!
       raise ArgumentError, "timeout must be positive" unless @timeout.is_a?(Numeric) && @timeout > 0
       raise ArgumentError, "max_retries must be non-negative" unless @max_retries.is_a?(Integer) && @max_retries >= 0
-      raise ArgumentError, "max_pages must be positive" unless @max_pages.is_a?(Integer) && @max_pages > 0
+      validate_max_pages!(@max_pages)
+    end
+
+    # Shared by validate! and the max_pages= writer. Integer-only, so a
+    # boolean or Float::INFINITY is refused along with zero and negatives.
+    def validate_max_pages!(value)
+      raise ArgumentError, "max_pages must be positive" unless value.is_a?(Integer) && value > 0
     end
 
     def normalize_url(url)

data/lib/basecamp/generated/metadata.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://basecamp.com/schemas/sdk-metadata.json",
   "version": "1.0.0",
-  "generated": "2026-08-07T11:12:00Z",
+  "generated": "2026-09-03T02:27:35Z",
   "operations": {
     "GetAccount": {
       "retry": {
@@ -1576,6 +1576,17 @@
         "maxPageSize": 50
       }
     },
+    "ListRecentProjects": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "MarkAsRead": {
       "retry": {
         "maxAttempts": 2,
@@ -1806,6 +1817,20 @@
         "natural": true
       }
     },
+    "RecordProjectVisit": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
     "UnarchiveProject": {
       "retry": {
         "maxAttempts": 3,
@@ -2144,6 +2169,34 @@
         ]
       }
     },
+    "CreateBubbleUp": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
+    "DeleteBubbleUp": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
     "SetClientVisibility": {
       "retry": {
         "maxAttempts": 3,
@@ -2228,6 +2281,34 @@
         ]
       }
     },
+    "SpotlightRecording": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
+    "UnspotlightRecording": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
     "UnarchiveRecording": {
       "retry": {
         "maxAttempts": 3,
@@ -2668,6 +2749,39 @@
         "natural": true
       }
     },
+    "GetTemplateLibrary": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
+    "CreateTemplateLibraryCopy": {
+      "retry": {
+        "maxAttempts": 2,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
+    "GetTemplateLibraryCopy": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "ListTemplates": {
       "retry": {
         "maxAttempts": 3,

data/lib/basecamp/generated/services/bubble_ups_service.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for BubbleUps operations
+    #
+    # @generated from OpenAPI spec
+    class BubbleUpsService < BaseService
+
+      # Bubble up a recording for the current user, resurfacing it in the current
+      # @param recording_id [Integer] recording id ID
+      # @param at [String, nil] Timing for the bubble-up. `"now"` bubbles up immediately; a scheduling
+      #   keyword (`"today"`, `"tomorrow"`, `"weekend"`, `"next_week"`) or an ISO8601
+      #   date (e.g. `"2026-09-10"`) schedules it to resurface later. bc3 requires a
+      #   value — omitting `at` errors server-side (`Date.iso8601(nil)`) — so send
+      #   `"now"` for the immediate case.
+      # @return [void]
+      def create_bubble_up(recording_id:, at: nil)
+        with_operation(service: "bubbleups", operation: "create_bubble_up", is_mutation: true, resource_id: recording_id) do
+          http_post("/recordings/#{recording_id}/bubble_up.json", body: compact_params(at: at))
+          nil
+        end
+      end
+
+      # Remove the current user's bubble-up from a recording (returns 204 No Content).
+      # @param recording_id [Integer] recording id ID
+      # @return [void]
+      def delete_bubble_up(recording_id:)
+        with_operation(service: "bubbleups", operation: "delete_bubble_up", is_mutation: true, resource_id: recording_id) do
+          http_delete("/recordings/#{recording_id}/bubble_up.json")
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/basecamp/generated/services/projects_service.rb

@@ -7,6 +7,14 @@ module Basecamp
     # @generated from OpenAPI spec
     class ProjectsService < BaseService
 
+      # List the projects the current user has most recently visited, most recent visit first.
+      # @return [Array<Hash>] response data
+      def list_recent_projects()
+        with_operation(service: "projects", operation: "list_recent_projects", is_mutation: false) do
+          http_get("/my/recent_projects.json", operation: "ListRecentProjects").json
+        end
+      end
+
       # List projects (active by default; optionally archived/trashed)
       # @param status [String, nil] active|archived|trashed
       # @param page [Integer, nil] Page number for paginating through results. Defaults to 1. A positive value selects exactly that page, not a starting offset; see SPEC section 8.
@@ -61,6 +69,16 @@ module Basecamp
         end
       end
 
+      # Record that the current user visited a project, moving it to the front of ListRecentProjects (returns 204 No Content).
+      # @param project_id [Integer] project id ID
+      # @return [void]
+      def record_project_visit(project_id:)
+        with_operation(service: "projects", operation: "record_project_visit", is_mutation: true, project_id: project_id) do
+          http_post("/projects/#{project_id}/recent_visit.json")
+          nil
+        end
+      end
+
       # Restore a project to active status from trash as well as from the archive (returns 204 No Content).
       # @param project_id [Integer] project id ID
       # @return [void]

data/lib/basecamp/generated/services/recordings_service.rb

@@ -23,6 +23,25 @@ module Basecamp
         end
       end
 
+      # Put a recording's card in the spotlight area on its project or template home page.
+      # @param recording_id [Integer] recording id ID
+      # @return [Hash] response data
+      def spotlight(recording_id:)
+        with_operation(service: "recordings", operation: "spotlight", is_mutation: true, resource_id: recording_id) do
+          http_post("/recordings/#{recording_id}/spotlight.json").json
+        end
+      end
+
+      # Remove a recording from the spotlight area.
+      # @param recording_id [Integer] recording id ID
+      # @return [void]
+      def unspotlight(recording_id:)
+        with_operation(service: "recordings", operation: "unspotlight", is_mutation: true, resource_id: recording_id) do
+          http_delete("/recordings/#{recording_id}/spotlight.json")
+          nil
+        end
+      end
+
       # Unarchive a recording (restore to active status)
       # @param recording_id [Integer] recording id ID
       # @return [void]

data/lib/basecamp/generated/services/templates_service.rb

@@ -7,6 +7,34 @@ module Basecamp
     # @generated from OpenAPI spec
     class TemplatesService < BaseService
 
+      # Get the account's to-do list template library
+      # @return [Hash] response data
+      def get_library()
+        with_operation(service: "templates", operation: "get_library", is_mutation: false) do
+          http_get("/template_library.json", operation: "GetTemplateLibrary").json
+        end
+      end
+
+      # Start copying a to-do list template into a project
+      # @param template_recording_id [Integer] template recording id
+      # @param destination_parent_id [Integer] destination parent id
+      # @param adding_people_confirmed [Boolean, nil] Confirm granting destination-project access to people referenced by the template.
+      # @return [Hash] response data
+      def create_library_copy(template_recording_id:, destination_parent_id:, adding_people_confirmed: nil)
+        with_operation(service: "templates", operation: "create_library_copy", is_mutation: true) do
+          http_post("/template_library/copies.json", body: compact_params(template_recording_id: template_recording_id, destination_parent_id: destination_parent_id, adding_people_confirmed: adding_people_confirmed)).json
+        end
+      end
+
+      # Get the current status of a to-do list template copy
+      # @param copy_id [Integer] copy id ID
+      # @return [Hash] response data
+      def get_library_copy(copy_id:)
+        with_operation(service: "templates", operation: "get_library_copy", is_mutation: false, resource_id: copy_id) do
+          http_get("/template_library/copies/#{copy_id}", operation: "GetTemplateLibraryCopy").json
+        end
+      end
+
       # List all templates visible to the current user
       # @param status [String, nil] active|archived|trashed
       # @param page [Integer, nil] Page number for paginating through results. Defaults to 1. A positive value selects exactly that page, not a starting offset; see SPEC section 8.