basecamp-sdk 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d41385ab7c36a096b4b54f56a0b60af4c6ab42e561e4bf147bdd850b77c8e230
-  data.tar.gz: e93de2347867e1f40afcee749d1e49a7873fffd4f656200bf5305e0fef813b29
+  metadata.gz: 9b770f1606323f83fb028ebb44d51e0d2500664a6d88ec9209dc227807ace197
+  data.tar.gz: 418cf25fbdc65f25db5e9d816565cd20a7f2e3d0c06c5a147dcf896c38d2ec9e
 SHA512:
-  metadata.gz: 8f33657f9328f7a786aa33925a96ab89786f655dd0f83db71f80b9fb9472c06bd2400a15b5637e964a00fc146a1dbae0f86b49157939f1df983f52838ec42380
-  data.tar.gz: 2db82e6a78234d1f12f6e54a139d490df8f0f5205135a23b8946435f75f7120e863659d3c3fdeb6ae3e57a7cb94b55a32a7ba4914aa1ad0c7ebfba08f701d59e
+  metadata.gz: 82caf3dad37f93e3b9ce65ad2da90b798efa466d0a2fc8e25d63ea84778357a436fe0da8615bbde3f03c3836eb9077dee20b35775ab283900437e575a64aa99e
+  data.tar.gz: c17f87a5bac84d66e89edf3725fb3321fa768b31d868d8214f1dbf8326a6361f73dd5acf355c4a22712a9434fe5514d0b750edd2eb8d6ce15468a0867f44419d

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
 
@@ -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/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-07T11:12:00Z",
   "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-07T11:12:00Z
 
 require "json"
 require "time"
@@ -5063,6 +5063,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

@@ -632,6 +632,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

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/services/authorization_service.rb

@@ -5,11 +5,20 @@ 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, a top-level +scope+ for BC3-issued tokens, and +expires_at+ as
+    # integer epoch seconds rather than ISO-8601. Only +identity.id+,
+    # +accounts[].id+, +accounts[].name+ and +accounts[].href+ are common to both.
+    #
     # @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"
+  VERSION = "0.14.0"
   API_VERSION = "2026-08-05"
 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.14.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-08-07 00:00:00.000000000 Z
+date: 2026-08-12 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