basecamp-sdk 0.13.0 → 0.15.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d41385ab7c36a096b4b54f56a0b60af4c6ab42e561e4bf147bdd850b77c8e230
-  data.tar.gz: e93de2347867e1f40afcee749d1e49a7873fffd4f656200bf5305e0fef813b29
+  metadata.gz: f6c1f02712a441b2b7772199b8029904b0c254be6c9b687a94a8d957f7d8a066
+  data.tar.gz: f0750c8e75561aaa908630440f0b2c4276a54abb653418361cc4363883497d9a
 SHA512:
-  metadata.gz: 8f33657f9328f7a786aa33925a96ab89786f655dd0f83db71f80b9fb9472c06bd2400a15b5637e964a00fc146a1dbae0f86b49157939f1df983f52838ec42380
-  data.tar.gz: 2db82e6a78234d1f12f6e54a139d490df8f0f5205135a23b8946435f75f7120e863659d3c3fdeb6ae3e57a7cb94b55a32a7ba4914aa1ad0c7ebfba08f701d59e
+  metadata.gz: a7d6ecde9f18d17b9baadc7b827b6d396c0f6e63ab304d93800ee2e35f3803af9d668965b5d5885a408d926e780700f7fe0320d68375924a6647cce2462eee20
+  data.tar.gz: a445a4123c2ebf596026035d347dbe99883b207a650003d2651f0dbc77eed9c0f4634703555e17af674aca87e015fdbe17f38a40e9370deff1b73a42cec6d042

data/README.md

@@ -2,7 +2,7 @@
 
 Official Ruby SDK for the [Basecamp API](https://github.com/basecamp/bc3-api).
 
-**Upgrading to v0.13.0?** Read [MIGRATING.md](../MIGRATING.md#ruby) before you bump the version — Ruby carries eleven breaks nothing catches at load time — ten with no signal at all, and one that raises only on a record where the field is populated.
+**Upgrading to v0.14.0?** Read [MIGRATING.md](../MIGRATING.md) before you bump the version — nothing catches either break at load time. `uploads.list_versions` entries now carry the version event's keys, with the file nested under `"upload"` — code reading `version["filename"]` was getting nil and now has a real place to look — and every 507 reports `limit_exceeded` instead of a retryable `api_error`, so a `when` falling through to an else arm reroutes storage, project and webhook limits silently. Coming from v0.12.0 or earlier, read v0.13.0's section too.
 
 ## Requirements
 
@@ -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 |
 |---------|-------------|
@@ -480,6 +480,7 @@ end
 | `ValidationError` | Invalid request data (400, 422) |
 | `RateLimitError` | Rate limit exceeded (429) |
 | `NetworkError` | Connection failures |
+| `LimitExceededError` | Account limit reached (507) — file storage, projects, webhooks |
 
 ### Validation Errors
 

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
@@ -616,7 +618,26 @@ 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?
+        raise ApiError.new("redirect to undialable download URL: #{Security.truncate(url)}")
+      end
+
       http_client = Net::HTTP.new(uri.host, uri.port)
       http_client.use_ssl = (uri.scheme == "https")
       http_client.open_timeout = config.timeout
@@ -625,11 +646,22 @@ 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)
       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)
         raise ApiError.new("download failed with status #{response.code}", http_status: response.code.to_i)
       end

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/error.rb

@@ -79,6 +79,7 @@ module Basecamp
       when ErrorCode::API then ExitCode::API
       when ErrorCode::AMBIGUOUS then ExitCode::AMBIGUOUS
       when ErrorCode::VALIDATION then ExitCode::VALIDATION
+      when ErrorCode::LIMIT_EXCEEDED then ExitCode::LIMIT_EXCEEDED
       else ExitCode::API
       end
     end

data/lib/basecamp/error_code.rb

@@ -12,5 +12,6 @@ module Basecamp
     API = "api_error"
     AMBIGUOUS = "ambiguous"
     VALIDATION = "validation"
+    LIMIT_EXCEEDED = "limit_exceeded"
   end
 end

data/lib/basecamp/exit_code.rb

@@ -13,5 +13,6 @@ module Basecamp
     API = 7
     AMBIGUOUS = 8
     VALIDATION = 9
+    LIMIT_EXCEEDED = 10
   end
 end

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-06T00:45:34Z",
+  "generated": "2026-08-12T19:58:36Z",
   "operations": {
     "GetAccount": {
       "retry": {
@@ -3148,6 +3148,17 @@
         "maxPageSize": 50
       }
     },
+    "CreateUploadVersion": {
+      "retry": {
+        "maxAttempts": 2,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "GetVault": {
       "retry": {
         "maxAttempts": 3,

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

@@ -37,6 +37,24 @@ module Basecamp
         end
       end
 
+      # Replace an upload's file with a new version
+      # @param upload_id [Integer] upload id ID
+      # @param attachable_sgid [String] attachable sgid
+      # @param base_name [String, nil] Omit to keep the uploaded file's own name. Sending "" also keeps it.
+      # @param description [String, nil] Presence-aware: omit to carry the previous version's description forward,
+      #   send "" to clear it, send a value to set it.
+      # @param notify [String, nil] Who to notify: "default", "everyone", or "custom" (the people in subscriptions).
+      #
+      #   Omit both this and subscriptions to notify nobody. A subscriptions array sent
+      #   without notify is read as "custom".
+      # @param subscriptions [Array, nil] People to notify about the replacement and subscribe to the upload.
+      # @return [Hash] response data
+      def create_version(upload_id:, attachable_sgid:, base_name: nil, description: nil, notify: nil, subscriptions: nil)
+        with_operation(service: "uploads", operation: "create_version", is_mutation: true, resource_id: upload_id) do
+          http_post("/uploads/#{upload_id}/versions.json", body: compact_params(attachable_sgid: attachable_sgid, base_name: base_name, description: description, notify: notify, subscriptions: subscriptions)).json
+        end
+      end
+
       # List uploads in a vault
       # @param vault_id [Integer] vault id ID
       # @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.

data/lib/basecamp/generated/types.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 # Auto-generated from OpenAPI spec. Do not edit manually.
-# Generated: 2026-08-06T00:45:34Z
+# Generated: 2026-08-12T19:58:36Z
 
 require "json"
 require "time"
@@ -2672,23 +2672,23 @@ module Basecamp
     # MyAssignmentAssignee
     class MyAssignmentAssignee
       include TypeHelpers
-      attr_accessor :id, :avatar_url, :name
+      attr_accessor :avatar_url, :id, :name
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[id].freeze
+        %i[avatar_url id name].freeze
       end
 
       def initialize(data = {})
-        @id = parse_integer(data["id"])
         @avatar_url = data["avatar_url"]
+        @id = parse_integer(data["id"])
         @name = data["name"]
       end
 
       def to_h
         {
-          "id" => @id,
           "avatar_url" => @avatar_url,
+          "id" => @id,
           "name" => @name,
         }.compact
       end
@@ -2955,23 +2955,23 @@ module Basecamp
     # OutOfOfficePerson
     class OutOfOfficePerson
       include TypeHelpers
-      attr_accessor :id, :avatar_url, :name
+      attr_accessor :avatar_url, :id, :name
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[id].freeze
+        %i[avatar_url id name].freeze
       end
 
       def initialize(data = {})
-        @id = parse_integer(data["id"])
         @avatar_url = data["avatar_url"]
+        @id = parse_integer(data["id"])
         @name = data["name"]
       end
 
       def to_h
         {
-          "id" => @id,
           "avatar_url" => @avatar_url,
+          "id" => @id,
           "name" => @name,
         }.compact
       end
@@ -4025,62 +4025,114 @@ module Basecamp
     # SearchResult
     class SearchResult
       include TypeHelpers
-      attr_accessor :app_url, :content, :description, :id, :title, :type, :url, :bookmark_url, :bubble_up_url, :bucket, :content_attachments, :created_at, :creator, :description_attachments, :inherits_status, :parent, :plain_text_content, :plain_text_description, :status, :subject, :updated_at, :visible_to_clients
+      attr_accessor :content, :description, :app_download_url, :app_url, :attachments, :bookmark_url, :boosts_count, :boosts_url, :bubble_up_url, :bucket, :byte_size, :cards_count, :cards_url, :color, :comment_count, :comments_count, :comments_url, :content_attachments, :content_type, :created_at, :creator, :description_attachments, :download_url, :filename, :height, :id, :image_url, :inherits_status, :language, :on_hold, :parent, :plain_text_content, :plain_text_description, :position, :preview_url, :previewable, :sound_url, :status, :subject, :subscribers, :subscription_url, :thumbnail_url, :title, :type, :updated_at, :url, :visible_to_clients, :width
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[app_url content description id title type url].freeze
+        %i[content description].freeze
       end
 
       def initialize(data = {})
-        @app_url = data["app_url"]
         @content = data["content"]
         @description = data["description"]
-        @id = parse_integer(data["id"])
-        @title = data["title"]
-        @type = data["type"]
-        @url = data["url"]
+        @app_download_url = data["app_download_url"]
+        @app_url = data["app_url"]
+        @attachments = parse_array(data["attachments"], "SearchResultAttachment")
         @bookmark_url = data["bookmark_url"]
+        @boosts_count = parse_integer(data["boosts_count"])
+        @boosts_url = data["boosts_url"]
         @bubble_up_url = data["bubble_up_url"]
         @bucket = parse_type(data["bucket"], "RecordingBucket")
+        @byte_size = parse_integer(data["byte_size"])
+        @cards_count = parse_integer(data["cards_count"])
+        @cards_url = data["cards_url"]
+        @color = data["color"]
+        @comment_count = parse_integer(data["comment_count"])
+        @comments_count = parse_integer(data["comments_count"])
+        @comments_url = data["comments_url"]
         @content_attachments = parse_array(data["content_attachments"], "RichTextAttachment")
+        @content_type = data["content_type"]
         @created_at = parse_datetime(data["created_at"])
         @creator = parse_type(data["creator"], "Person")
         @description_attachments = parse_array(data["description_attachments"], "RichTextAttachment")
+        @download_url = data["download_url"]
+        @filename = data["filename"]
+        @height = parse_integer(data["height"])
+        @id = parse_integer(data["id"])
+        @image_url = data["image_url"]
         @inherits_status = parse_boolean(data["inherits_status"])
+        @language = data["language"]
+        @on_hold = parse_type(data["on_hold"], "CardColumnOnHold")
         @parent = parse_type(data["parent"], "RecordingParent")
         @plain_text_content = data["plain_text_content"]
         @plain_text_description = data["plain_text_description"]
+        @position = parse_integer(data["position"])
+        @preview_url = data["preview_url"]
+        @previewable = parse_boolean(data["previewable"])
+        @sound_url = data["sound_url"]
         @status = data["status"]
         @subject = data["subject"]
+        @subscribers = parse_array(data["subscribers"], "Person")
+        @subscription_url = data["subscription_url"]
+        @thumbnail_url = data["thumbnail_url"]
+        @title = data["title"]
+        @type = data["type"]
         @updated_at = parse_datetime(data["updated_at"])
+        @url = data["url"]
         @visible_to_clients = parse_boolean(data["visible_to_clients"])
+        @width = parse_integer(data["width"])
       end
 
       def to_h
         {
-          "app_url" => @app_url,
           "content" => @content,
           "description" => @description,
-          "id" => @id,
-          "title" => @title,
-          "type" => @type,
-          "url" => @url,
+          "app_download_url" => @app_download_url,
+          "app_url" => @app_url,
+          "attachments" => @attachments,
           "bookmark_url" => @bookmark_url,
+          "boosts_count" => @boosts_count,
+          "boosts_url" => @boosts_url,
           "bubble_up_url" => @bubble_up_url,
           "bucket" => @bucket,
+          "byte_size" => @byte_size,
+          "cards_count" => @cards_count,
+          "cards_url" => @cards_url,
+          "color" => @color,
+          "comment_count" => @comment_count,
+          "comments_count" => @comments_count,
+          "comments_url" => @comments_url,
           "content_attachments" => @content_attachments,
+          "content_type" => @content_type,
           "created_at" => @created_at,
           "creator" => @creator,
           "description_attachments" => @description_attachments,
+          "download_url" => @download_url,
+          "filename" => @filename,
+          "height" => @height,
+          "id" => @id,
+          "image_url" => @image_url,
           "inherits_status" => @inherits_status,
+          "language" => @language,
+          "on_hold" => @on_hold,
           "parent" => @parent,
           "plain_text_content" => @plain_text_content,
           "plain_text_description" => @plain_text_description,
+          "position" => @position,
+          "preview_url" => @preview_url,
+          "previewable" => @previewable,
+          "sound_url" => @sound_url,
           "status" => @status,
           "subject" => @subject,
+          "subscribers" => @subscribers,
+          "subscription_url" => @subscription_url,
+          "thumbnail_url" => @thumbnail_url,
+          "title" => @title,
+          "type" => @type,
           "updated_at" => @updated_at,
+          "url" => @url,
           "visible_to_clients" => @visible_to_clients,
+          "width" => @width,
         }.reject { |k, v| v.nil? && !["content", "description"].include?(k) }
       end
 
@@ -4089,6 +4141,55 @@ module Basecamp
       end
     end
 
+    # SearchResultAttachment
+    class SearchResultAttachment
+      include TypeHelpers
+      attr_accessor :byte_size, :content_type, :download_url, :filename, :height, :id, :preview_url, :previewable, :sgid, :thumbnail_url, :title, :url, :width
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[byte_size content_type download_url filename].freeze
+      end
+
+      def initialize(data = {})
+        @byte_size = parse_integer(data["byte_size"])
+        @content_type = data["content_type"]
+        @download_url = data["download_url"]
+        @filename = data["filename"]
+        @height = parse_integer(data["height"])
+        @id = parse_integer(data["id"])
+        @preview_url = data["preview_url"]
+        @previewable = parse_boolean(data["previewable"])
+        @sgid = data["sgid"]
+        @thumbnail_url = data["thumbnail_url"]
+        @title = data["title"]
+        @url = data["url"]
+        @width = parse_integer(data["width"])
+      end
+
+      def to_h
+        {
+          "byte_size" => @byte_size,
+          "content_type" => @content_type,
+          "download_url" => @download_url,
+          "filename" => @filename,
+          "height" => @height,
+          "id" => @id,
+          "preview_url" => @preview_url,
+          "previewable" => @previewable,
+          "sgid" => @sgid,
+          "thumbnail_url" => @thumbnail_url,
+          "title" => @title,
+          "url" => @url,
+          "width" => @width,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
     # SearchType
     class SearchType
       include TypeHelpers
@@ -4722,39 +4823,53 @@ module Basecamp
     # Tool
     class Tool
       include TypeHelpers
-      attr_accessor :created_at, :enabled, :id, :name, :title, :updated_at, :app_url, :bucket, :position, :status, :url
+      attr_accessor :created_at, :creator, :id, :inherits_status, :title, :type, :updated_at, :visible_to_clients, :app_url, :bookmark_url, :bucket, :enabled, :name, :parent, :position, :status, :subscription_url, :url
 
       # @return [Array<Symbol>]
       def self.required_fields
-        %i[created_at enabled id name title updated_at].freeze
+        %i[created_at creator id inherits_status title type updated_at visible_to_clients].freeze
       end
 
       def initialize(data = {})
         @created_at = parse_datetime(data["created_at"])
-        @enabled = parse_boolean(data["enabled"])
+        @creator = parse_type(data["creator"], "Person")
         @id = parse_integer(data["id"])
-        @name = data["name"]
+        @inherits_status = parse_boolean(data["inherits_status"])
         @title = data["title"]
+        @type = data["type"]
         @updated_at = parse_datetime(data["updated_at"])
+        @visible_to_clients = parse_boolean(data["visible_to_clients"])
         @app_url = data["app_url"]
+        @bookmark_url = data["bookmark_url"]
         @bucket = parse_type(data["bucket"], "RecordingBucket")
+        @enabled = parse_boolean(data["enabled"])
+        @name = data["name"]
+        @parent = parse_type(data["parent"], "RecordingParent")
         @position = parse_integer(data["position"])
         @status = data["status"]
+        @subscription_url = data["subscription_url"]
         @url = data["url"]
       end
 
       def to_h
         {
           "created_at" => @created_at,
-          "enabled" => @enabled,
+          "creator" => @creator,
           "id" => @id,
-          "name" => @name,
+          "inherits_status" => @inherits_status,
           "title" => @title,
+          "type" => @type,
           "updated_at" => @updated_at,
+          "visible_to_clients" => @visible_to_clients,
           "app_url" => @app_url,
+          "bookmark_url" => @bookmark_url,
           "bucket" => @bucket,
+          "enabled" => @enabled,
+          "name" => @name,
+          "parent" => @parent,
           "position" => @position,
           "status" => @status,
+          "subscription_url" => @subscription_url,
           "url" => @url,
         }.compact
       end
@@ -5063,6 +5178,82 @@ module Basecamp
       end
     end
 
+    # UploadVersion
+    class UploadVersion
+      include TypeHelpers
+      attr_accessor :action, :created_at, :creator, :id, :recording_id, :boosts_count, :boosts_url, :details, :upload
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[action created_at creator id recording_id].freeze
+      end
+
+      def initialize(data = {})
+        @action = data["action"]
+        @created_at = parse_datetime(data["created_at"])
+        @creator = parse_type(data["creator"], "Person")
+        @id = parse_integer(data["id"])
+        @recording_id = parse_integer(data["recording_id"])
+        @boosts_count = parse_integer(data["boosts_count"])
+        @boosts_url = data["boosts_url"]
+        @details = parse_type(data["details"], "EventDetails")
+        @upload = parse_type(data["upload"], "UploadVersionFile")
+      end
+
+      def to_h
+        {
+          "action" => @action,
+          "created_at" => @created_at,
+          "creator" => @creator,
+          "id" => @id,
+          "recording_id" => @recording_id,
+          "boosts_count" => @boosts_count,
+          "boosts_url" => @boosts_url,
+          "details" => @details,
+          "upload" => @upload,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    # UploadVersionFile
+    class UploadVersionFile
+      include TypeHelpers
+      attr_accessor :app_download_url, :current, :download_url, :filename, :byte_size, :content_type
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[app_download_url current download_url filename].freeze
+      end
+
+      def initialize(data = {})
+        @app_download_url = data["app_download_url"]
+        @current = parse_boolean(data["current"])
+        @download_url = data["download_url"]
+        @filename = data["filename"]
+        @byte_size = parse_integer(data["byte_size"])
+        @content_type = data["content_type"]
+      end
+
+      def to_h
+        {
+          "app_download_url" => @app_download_url,
+          "current" => @current,
+          "download_url" => @download_url,
+          "filename" => @filename,
+          "byte_size" => @byte_size,
+          "content_type" => @content_type,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
     # Vault
     class Vault
       include TypeHelpers

data/lib/basecamp/http.rb

@@ -342,7 +342,16 @@ module Basecamp
       Http.normalize_person_ids(data)
       data
     rescue JSON::ParserError => e
-      raise Basecamp::ApiError.new("Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}")
+      # +cause+ carries the parser's own error, not just its message (#750). The
+      # message says what happened; the slot is what a caller can act on, and it
+      # is the same answer Go reaches through errors.As and Kotlin and Swift
+      # through their decodeFailure slot. Passed explicitly rather than left to
+      # Ruby's implicit +$!+ chaining because Basecamp::Error defines its own
+      # +cause+ reader.
+      raise Basecamp::ApiError.new(
+        "Failed to parse paginated response (page #{page}): #{Security.truncate(e.message)}",
+        cause: e
+      )
     end
 
     # Extracts the item array from a parsed page body: the body itself for
@@ -493,8 +502,10 @@ module Basecamp
     # Memoized per-operation retry metadata, keyed by canonical operation ID.
     # Benign-race memoization: concurrent first loads compute identical values.
     def self.operation_retry(operation)
+      # UTF-8 regardless of process locale — JSON is UTF-8 (RFC 8259), and
+      # LC_ALL=C would otherwise read as US-ASCII.
       @operation_metadata ||= JSON.parse(
-        File.read(File.join(__dir__, "generated", "metadata.json"))
+        File.read(File.join(__dir__, "generated", "metadata.json"), encoding: "UTF-8")
       ).fetch("operations").freeze
       @operation_metadata.dig(operation, "retry")
     end
@@ -632,6 +643,12 @@ module Basecamp
           Basecamp.compose_validation_message(Basecamp.parse_error_message(body), field_errors) || "Validation failed"
         )
         Basecamp::ValidationError.new(message, http_status: status, field_errors: field_errors)
+      when 507
+        # A 5xx status carrying a client fact: the account is out of storage, or
+        # at its webhook ceiling. Retrying cannot satisfy it, so this is decided
+        # before the 5xx arms below.
+        message = Security.truncate(Basecamp.parse_error_message(body) || "Account limit reached")
+        Basecamp::LimitExceededError.new(message)
       when 500
         Basecamp::ApiError.new("Server error (500)", http_status: 500, retryable: true)
       when 502, 503, 504
@@ -779,6 +796,32 @@ module Basecamp
     end
 
     def parse_next_link(link_header)
+      # A non-ASCII-compatible tag (UTF-16/32; only a stub or custom adapter
+      # produces one — Faraday's Net::HTTP adapter always yields ASCII-8BIT)
+      # defeats the byte scan below: "<" is 3C 00 in UTF-16LE, so the ASCII
+      # literals never match and a genuinely UTF-16LE header parsed to nil
+      # silently, where the pre-#678 character path at least crashed loudly.
+      # Transcoding to UTF-8 up front restores parsing for that case, and
+      # rebinding the local means the retag at the bottom hands back UTF-8.
+      #
+      # ASCII bytes MIStagged UTF-16LE split by bytesize parity, and both
+      # outcomes are deliberate:
+      #   - odd (the natural case): invalid UTF-16LE, encode raises, and the
+      #     fallthrough keeps today's refusal — the scan extracts the URL
+      #     still mistagged, and Security.same_origin? refuses the follow
+      #     (ApiError), so no origin-check bypass opens up.
+      #   - even: valid UTF-16LE by construction, transcodes to CJK mojibake
+      #     with no rel="next", parses to nil (was: the ApiError above).
+      #     Garbage-tagged garbage; nil is as good a refusal as a raise.
+      unless link_header.nil? || link_header.encoding.ascii_compatible?
+        begin
+          link_header = link_header.encode(Encoding::UTF_8)
+        rescue Encoding::UndefinedConversionError, Encoding::InvalidByteSequenceError,
+               Encoding::ConverterNotFoundError
+          # Not decodable under its claimed encoding — scan the raw bytes.
+        end
+      end
+
       next_url = nil
 
       unless link_header.nil? || link_header.empty?

data/lib/basecamp/limit_exceeded_error.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+module Basecamp
+  # Raised when an account limit blocks the request (HTTP 507) — file storage
+  # exhausted, or a webhook ceiling reached.
+  #
+  # Never retryable: no amount of backoff frees storage or raises a plan limit.
+  # That is the whole reason this is not an ApiError, which a 507 would
+  # otherwise become through the 5xx catch-all.
+  class LimitExceededError < Error
+    def initialize(message = "Account limit reached", hint: nil, cause: nil)
+      super(
+        code: ErrorCode::LIMIT_EXCEEDED,
+        message: message,
+        hint: hint,
+        http_status: 507,
+        retryable: false,
+        cause: cause
+      )
+    end
+  end
+end

data/lib/basecamp/security.rb

@@ -39,13 +39,19 @@ module Basecamp
 
       ua.scheme.downcase == ub.scheme.downcase &&
         normalize_host(ua) == normalize_host(ub)
-    rescue URI::InvalidURIError
+    rescue URI::Error
+      # URI::Error, not just InvalidURIError: URI.parse("mailto:") raises
+      # URI::InvalidComponentError (URI::MailTo demands an opaque part), and a
+      # scheme-only URL must be refused, not a crash.
       false
     end
 
     def self.resolve_url(base, target)
       URI.join(base, target).to_s
-    rescue URI::InvalidURIError
+    rescue URI::Error
+      # URI::Error, not just InvalidURIError: URI.join raises
+      # URI::InvalidComponentError on a scheme-only target ("mailto:"),
+      # reachable from a poisoned Link header or Location redirect.
       target
     end
 

data/lib/basecamp/services/authorization_service.rb

@@ -5,11 +5,22 @@ module Basecamp
     # Service for authorization operations.
     # This is the only service that doesn't require an account context.
     #
+    # The document's shape depends on which issuer served it. Discovery selects a
+    # BC5 issuer whenever one is advertised, and a BC5 issuer serves its *own*
+    # document (+app/views/api/authorizations/show.json.jbuilder+), which is not
+    # Launchpad's: it carries +identity.id+ and nothing else of the identity, no
+    # +product+ or +app_href+ on accounts, an RFC 8707 +resource+ indicator
+    # instead, and a top-level +scope+ for BC3-issued tokens. Only +identity.id+,
+    # +accounts[].id+, +accounts[].name+, +accounts[].href+ and +expires_at+ are
+    # common to both; +expires_at+ is an ISO-8601 string from either issuer
+    # (integer epoch seconds from bc3 before bc3 #12646 — passed through
+    # verbatim either way).
+    #
     # @example Get authorization info
     #   auth = client.authorization.get
-    #   puts "Identity: #{auth["identity"]["email_address"]}"
+    #   puts "Identity: #{auth["identity"]["id"]}"
     #   auth["accounts"].each do |account|
-    #     puts "Account: #{account["name"]} (#{account["id"]})"
+    #     puts "Account: #{account["name"]} (#{account["href"]})"
     #   end
     class AuthorizationService < BaseService
       # Gets authorization information for the current user.

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.13.0"
-  API_VERSION = "2026-08-05"
+  VERSION = "0.15.0"
+  API_VERSION = "2026-08-11"
 end

data/lib/basecamp.rb

@@ -132,6 +132,10 @@ module Basecamp
       NotFoundError.new(message: message)
     when 429
       RateLimitError.new(retry_after: retry_after)
+    when 507
+      # Decided before the 5xx arms: a 507 is an account limit, not a
+      # transient server failure, and no retry can satisfy it.
+      LimitExceededError.new(Security.truncate(message))
     when 500
       ApiError.new("Server error (500)", http_status: 500, retryable: true)
     when 502, 503, 504

data/scripts/generate-metadata.rb

@@ -14,7 +14,9 @@ class MetadataExtractor
   METHODS = %w[get post put patch delete].freeze
 
   def initialize(openapi_path)
-    @openapi = JSON.parse(File.read(openapi_path))
+    # Read as UTF-8 regardless of process locale (LC_ALL=C would otherwise read
+    # as US-ASCII and JSON.parse dies on the spec's multibyte characters)
+    @openapi = JSON.parse(File.read(openapi_path, encoding: 'UTF-8'))
   end
 
   def extract

data/scripts/generate-services.rb

@@ -65,7 +65,7 @@ class ServiceGenerator
     },
     'Files' => {
       'Attachments' => %w[CreateAttachment],
-      'Uploads' => %w[GetUpload UpdateUpload ListUploads CreateUpload ListUploadVersions],
+      'Uploads' => %w[GetUpload UpdateUpload ListUploads CreateUpload ListUploadVersions CreateUploadVersion],
       'Vaults' => %w[GetVault UpdateVault ListVaults CreateVault],
       'Documents' => %w[GetDocument ReplaceDocument ListDocuments CreateDocument],
       'CloudFiles' => %w[GetCloudFile CreateCloudFile UpdateCloudFile],
@@ -217,6 +217,7 @@ class ServiceGenerator
     'ListUploads' => 'list',
     'CreateUpload' => 'create',
     'ListUploadVersions' => 'list_versions',
+    'CreateUploadVersion' => 'create_version',
     'GetMessage' => 'get',
     'UpdateMessage' => 'update',
     'CreateMessage' => 'create',
@@ -320,7 +321,8 @@ class ServiceGenerator
   ].freeze
 
   def initialize(openapi_path)
-    @openapi = JSON.parse(File.read(openapi_path))
+    # UTF-8 regardless of process locale — see generate-metadata.rb
+    @openapi = JSON.parse(File.read(openapi_path, encoding: 'UTF-8'))
     @schemas = @openapi.dig('components', 'schemas') || {}
   end
 

data/scripts/generate-types.rb

@@ -131,7 +131,8 @@ if __FILE__ == $PROGRAM_NAME
   puts '  module Types'
   puts '    include TypeHelpers'
 
-  schemas = JSON.parse(File.read(openapi_path))['components']['schemas'] || {}
+  # UTF-8 regardless of process locale — see generate-metadata.rb
+  schemas = JSON.parse(File.read(openapi_path, encoding: 'UTF-8'))['components']['schemas'] || {}
   sorted = schemas.keys.sort
 
   sorted.each do |name|

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.15.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-07 00:00:00.000000000 Z
+date: 2026-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -235,6 +235,7 @@ files:
 - lib/basecamp/generated/types.rb
 - lib/basecamp/hooks.rb
 - lib/basecamp/http.rb
+- lib/basecamp/limit_exceeded_error.rb
 - lib/basecamp/list_enumerator.rb
 - lib/basecamp/list_meta.rb
 - lib/basecamp/logger_hooks.rb