basecamp-sdk 0.12.0 → 0.13.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 99e64617bcf9bcf031f03ea1ae0311f37f46c5da4ac4fba9caeca9a768e44a22
-  data.tar.gz: 83dd4b5a6d15ffc7909121dc742e2ccbaf9d1159d2b743a8482bb5a1cd17241f
+  metadata.gz: d41385ab7c36a096b4b54f56a0b60af4c6ab42e561e4bf147bdd850b77c8e230
+  data.tar.gz: e93de2347867e1f40afcee749d1e49a7873fffd4f656200bf5305e0fef813b29
 SHA512:
-  metadata.gz: 1e5ce39f93f07dad1c1b79b2da9ac39db5ac70e8871eba73af86a92eb986d56f5b4002af55c40eb16a8f4bed14d2407ead7c1be3b5c817664dcf5033397db7eb
-  data.tar.gz: 5263d6241a9de95303c8a546efe7f412db59def57207a0e0f8c22c45ab06d0b40b4d2c05e7b4d7ab05e02d7cb451246a5ccb5c4992afb52127541b464dbeeb3e
+  metadata.gz: 8f33657f9328f7a786aa33925a96ab89786f655dd0f83db71f80b9fb9472c06bd2400a15b5637e964a00fc146a1dbae0f86b49157939f1df983f52838ec42380
+  data.tar.gz: 2db82e6a78234d1f12f6e54a139d490df8f0f5205135a23b8946435f75f7120e863659d3c3fdeb6ae3e57a7cb94b55a32a7ba4914aa1ad0c7ebfba08f701d59e

data/README.md

@@ -2,6 +2,8 @@
 
 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.
+
 ## Requirements
 
 - Ruby 3.2+
@@ -21,6 +23,49 @@ Or install directly:
 gem install basecamp-sdk
 ```
 
+## Getting a token
+
+Every Basecamp API request carries an OAuth 2.0 access token. There is no API key and no personal access token, so even a throwaway script starts here:
+
+1. Choose the grant that matches how your code runs:
+
+| Your integration | Grant | Who refreshes the token |
+|---|---|---|
+| already holds a token you obtained elsewhere | **static token** — [`Token Providers`](#token-providers) | you do |
+| can receive a browser redirect (web app, or a local callback server) | **authorization code + PKCE** — [`OAuth Flow Helpers`](#oauth-flow-helpers) | `OauthTokenProvider` |
+| has no browser, but a person can approve on another device (CLI, headless server, TV) | **device flow** — [`Device Authorization Grant`](#device-authorization-grant-rfc-8628) | `Basecamp::Oauth.refresh_token`, echoing the token's `resource` — **not** `OauthTokenProvider` |
+
+The one-line rule: **a redirect URI you control → authorization code; no browser but someone to approve → device flow; a token already in hand → static token.** An unattended daemon or CI job fits none of the three on its own — the device flow needs a person to enter the user code at the verification URI — so provision a token out of band and hand it to the process as a static or refresh token.
+
+2. Get the client credentials that grant needs:
+
+- **Authorization code + PKCE** — register your own integration at **<https://launchpad.37signals.com/integrations>**. You get a client ID, a client secret, and whatever redirect URI you nominated.
+- **Device flow** — nothing to register. It runs as the pre-registered public `basecamp-cli` client, which sends no secret, against the device endpoint that discovery returns. Launchpad advertises no device endpoint, so a client you register there is not the one this flow uses.
+- **Static token** — nothing to register; you already hold the token.
+
+`StaticTokenProvider` hands back the string you gave it and nothing more — it never refreshes, so once the token expires every call fails with `401` until you supply a new one. Use it to get a first successful call, then move to a refreshing path before you ship — `OauthTokenProvider` for an authorization-code token from Launchpad, or, for a device-flow token, `Basecamp::Oauth.refresh_token` echoing the stored `resource`. Do not hand a device-flow token to `OauthTokenProvider`: it refreshes only against Launchpad and sends no `resource`, so it fails at the first expiry.
+
+## Finding your account ID
+
+Every API path is scoped to an account — `https://3.basecampapi.com/{accountId}/…` — so `for_account` needs that number before your first call. One token can reach several accounts, so ask the token which. `authorization` hangs off the *top-level* client because it takes no account context. Unlike the other SDKs that ship this service (Go, Python, TypeScript all hardcode Launchpad), Ruby does not: `Http#get_authorization_document` runs resource-first discovery (SPEC.md §16) against your configured base URL and fetches `/authorization.json` from the *selected* issuer, reaching Launchpad only on a soft fallback. Point egress rules and HTTP stubs at the issuer discovery selects, not at Launchpad; a hard selection failure raises `Basecamp::Oauth::DiscoverySelectionError` before any credentialed request goes out.
+
+```ruby
+client = Basecamp.client(access_token: ENV["BASECAMP_TOKEN"])
+
+info = client.authorization.get
+# "bc3" is Basecamp; the same response also carries "hey" and other products,
+# and they are not ordered — filter before you pick, or you may scope the
+# client to a HEY account.
+basecamp_accounts = info["accounts"].select { |a| a["product"] == "bc3" }
+basecamp_accounts.each do |a|
+  puts "#{a["id"]}: #{a["name"]}"
+end
+
+account = client.for_account(basecamp_accounts.first["id"])
+```
+
+The response is parsed JSON with **string** keys, not symbols. `info["expires_at"]` tells you how long the token has left, which is the quickest way to confirm a static token has not lapsed.
+
 ## Quick Start
 
 ```ruby
@@ -316,7 +361,10 @@ The SDK provides 46 account-scoped services. The table below covers the common o
 
 ## Pagination
 
-All list methods return lazy Enumerators that automatically handle pagination:
+All list methods return a lazy `ListEnumerator` — an `Enumerator` subclass
+that automatically handles pagination and carries metadata. The first page is
+fetched when the method is called; later pages are fetched only as iteration
+demands them:
 
 ```ruby
 # Automatically fetches all pages
@@ -324,13 +372,56 @@ account.projects.list.each do |project|
   puts project["name"]
 end
 
-# Take only what you need
+# Take only what you need — no extra pages are fetched
 first_10 = account.todos.list(todolist_id: 456).take(10)
 
 # Convert to array (fetches all pages)
 all_projects = account.projects.list.to_a
 ```
 
+Pagination is automatic: the SDK follows Link headers up to `config.max_pages`
+(default: 10,000). The enumerator's `meta` exposes pagination metadata:
+
+```ruby
+projects = account.projects.list
+projects.meta.total_count  # X-Total-Count from the first page (0 if absent),
+                           # available immediately — page 1 is fetched eagerly
+projects.to_a
+projects.meta.truncated    # true if items beyond those yielded were available
+```
+
+Every list method also accepts a `max_items` keyword to cap how many items are
+yielded. Enumeration stops as soon as the cap is met, without fetching further
+pages. Zero or negative values disable the cap, as in the other SDKs:
+
+```ruby
+recent = account.projects.list(max_items: 50)
+recent.to_a
+recent.meta.truncated  # true only if more items were available
+```
+
+`meta.truncated` is final once enumeration completes, and is `true` only when
+items beyond those yielded were available — items were dropped by `max_items`,
+or the last-fetched page still advertised a next page when enumeration stopped
+(at `max_items` or the `max_pages` safety cap). Landing exactly on the final
+item is not truncation: when `truncated` is `false` after full enumeration,
+the result is definitely complete.
+
+### The `page` keyword
+
+A positive `page` selects exactly that page: one request, that page's items,
+no link-following.
+
+```ruby
+page_3 = account.projects.list(page: 3).to_a
+```
+
+Omit `page` (or pass `0`) to auto-paginate the whole collection. `max_items`
+still trims a pinned page.
+
+All six SDKs share these semantics — one request, that page only, no
+link-following. See SPEC section 8.
+
 ## Downloading Files
 
 Fetch an upload's file content in one call. The SDK fetches the upload
@@ -352,14 +443,14 @@ result = account.download_url(url)
 
 ## Retry Behavior
 
-Only plain GET requests retry — automatically, with exponential backoff. Mutation operations (POST, PUT, DELETE) do **not** retry to prevent data duplication, and the raw upload and download paths skip the retry loop entirely (the upload path is strictly one request; the download hop keeps only the one-shot 401 replay below).
+Only plain GET requests retry — automatically, with exponential backoff. Mutation operations (POST, PUT, DELETE) do **not** retry to prevent data duplication, and the raw upload path skips the retry loop entirely — it is strictly one request. The download flow's authenticated first hop does retry, but under its own declared status set (`429`, `502`, `503`, `504` — never `500`); its second hop, the fetch from the signed URL, is a single unauthenticated request.
 
-- **Which errors**: Retry keys off the error's `retryable?` classification, not a declared status list — 429 (rate limit), 500, 502, 503, 504, and any other 5xx all retry, as does `NetworkError` (connection failures, including DNS and connect-phase timeouts). Read timeouts are the exception: Faraday surfaces them as a status-less `ApiError` with `retryable? == false`, so a GET that times out mid-response fails on the first attempt. 400, 401, 403, 404, and 422 never retry.
-- **`max_retries`**: Total request attempts for GET requests, including the initial request — the default `3` means one initial attempt plus two retries. **`max_retries: 0` sends zero requests** and raises `Basecamp::ApiError` (`"Request failed after 0 attempts"`).
+- **Which errors**: A GET issued through a generated service carries its operation ID and is **governed** — status retries are gated on the statuses that operation declares, which is `[429, 503]` for every operation in the current metadata. A governed GET does **not** retry 500. Only the handful of GETs that carry no operation ID (`get_absolute`, OAuth discovery) fall back to the error taxonomy, where 429, 500, 502, 503, 504, and any other 5xx all retry. `NetworkError` (connection failures, including DNS and connect-phase timeouts) retries on both paths, since it has no status to gate on. Read timeouts are the exception: Faraday surfaces them as a status-less `ApiError` with `retryable? == false`, so a GET that times out mid-response fails on the first attempt. 400, 401, 403, 404, and 422 never retry.
+- **`max_retries`**: Total request attempts for GET requests, including the initial request — the default `3` means one initial attempt plus two retries. `max_retries: 0` is floored to a single attempt rather than sending zero requests.
 - **Backoff**: Exponential with jitter — `base_delay * 2^(attempt - 1) + rand * max_jitter` — uncapped, bounded in practice by the attempt budget.
 - **Rate limits**: A 429's `Retry-After` header overrides the calculated backoff. Only 429 carries it: 5xx and network errors always use the exponential backoff.
 - **401 responses**: With a refresh-capable token provider, the SDK refreshes the token and replays the request **once** — for all methods, including mutations — outside the `max_retries` budget. A second 401 is surfaced. The raw upload path has no 401 replay.
-- **Per-operation metadata**: The retry policy operations declare (`retry_on` statuses, per-operation `max`) is inert in Ruby — every API GET issued through the client, including the Launchpad authorization fetch, rides the same classification-based loop bounded by `config.max_retries` alone. (The download flow's redirect hop and OAuth discovery use their own single-attempt transports.)
+- **Per-operation metadata**: Every GET a generated service issues passes its canonical operation ID, so essentially all SDK reads are **governed**: attempts are bounded by `min(config.max_retries, operation max)` and status retries are gated on the operation's declared `retry_on`. The GETs that carry no operation ID — `get_absolute` and the Launchpad authorization fetch it backs — are **ungoverned** and ride the classification-based loop bounded by `config.max_retries` alone. The declared `base_delay_ms` and `backoff` are inert in Ruby either way: the backoff is always the client's. (OAuth discovery uses its own single-attempt transport.)
 - **`retryable?`**: Unlike SDKs where the error classification is only a hint for your own code, in Ruby an error's `retryable?` (and `retry_after`) is exactly what the transport acts on for GET requests.
 
 ## Error Handling
@@ -390,6 +481,27 @@ end
 | `RateLimitError` | Rate limit exceeded (429) |
 | `NetworkError` | Connection failures |
 
+### Validation Errors
+
+Basecamp rejects invalid writes with a body keyed by field. The SDK folds those
+messages into the message and keeps the raw map in `field_errors`, so you can
+drive a form without re-parsing the message:
+
+```ruby
+begin
+  account.calendars.update_calendar(calendar_id: calendar_id, calendar: { "color" => "chartreuse" })
+rescue Basecamp::ValidationError => e
+  puts e.message # => "color: is not a valid color"
+
+  e.field_errors&.each do |field, messages|
+    messages.each { |message| puts "  #{field} #{message}" }
+  end
+end
+```
+
+`field_errors` is `nil` for every other error shape, and its messages are the
+raw ones — the message is capped at 500 bytes, the map is not.
+
 ## Observability Hooks
 
 Monitor SDK behavior with hooks:
@@ -424,14 +536,21 @@ client = Basecamp::Client.new(
 
 ## Environment Variables
 
+`Basecamp::Config.from_env` (and `#load_from_env` on an existing config) reads these three. They are the only `BASECAMP_*` variables the SDK reads anywhere; the sole other environment read is `XDG_CONFIG_HOME`, for `Config.global_config_dir`.
+
 | Variable | Description |
 |----------|-------------|
-| `BASECAMP_TOKEN` | OAuth access token |
-| `BASECAMP_ACCOUNT_ID` | Account ID |
 | `BASECAMP_BASE_URL` | API base URL (default: `https://3.basecampapi.com`) |
 | `BASECAMP_TIMEOUT` | Request timeout in seconds (default: `30`) |
 | `BASECAMP_MAX_RETRIES` | Total request attempts for GET requests, including the initial request (default: `3`) |
 
+```ruby
+config = Basecamp::Config.from_env
+client = Basecamp::Client.new(config: config, token_provider: token_provider)
+```
+
+Credentials are **not** among them. `BASECAMP_TOKEN` and `BASECAMP_ACCOUNT_ID` appear in the examples above only because the caller reads them and passes the values in; the SDK never looks them up. Pass the token to `Basecamp.client(access_token:)` or `StaticTokenProvider`, and the account ID to `#for_account`.
+
 ## Development
 
 ```bash

data/lib/basecamp/client.rb

@@ -202,10 +202,12 @@ module Basecamp
     # Fetches all pages of a paginated resource.
     # @param path [String] URL path (without account prefix)
     # @param params [Hash] query parameters
+    # @param max_items [Integer, nil] cap on items yielded across pages;
+    #   nil or non-positive means no cap
     # @yield [Hash] each item from the response
-    # @return [Enumerator] if no block given
-    def paginate(path, params: {}, operation: nil, &)
-      @parent.http.paginate(account_path(path), params: params, operation: operation, &)
+    # @return [ListEnumerator] metadata-carrying lazy enumerator
+    def paginate(path, params: {}, operation: nil, max_items: nil, &)
+      @parent.http.paginate(account_path(path), params: params, operation: operation, max_items: max_items, &)
     end
 
     # Fetches all pages of a paginated resource, extracting items from a key.
@@ -213,19 +215,25 @@ module Basecamp
     # @param path [String] URL path (without account prefix)
     # @param key [String] the key containing the array of items
     # @param params [Hash] query parameters
+    # @param max_items [Integer, nil] cap on items yielded across pages;
+    #   nil or non-positive means no cap
     # @yield [Hash] each item from the response
-    # @return [Enumerator] if no block given
-    def paginate_key(path, key:, params: {}, operation: nil, &)
-      @parent.http.paginate_key(account_path(path), key: key, params: params, operation: operation, &)
+    # @return [ListEnumerator] metadata-carrying lazy enumerator
+    def paginate_key(path, key:, params: {}, operation: nil, max_items: nil, &)
+      @parent.http.paginate_key(account_path(path), key: key, params: params, operation: operation, \
+        max_items: max_items, &)
     end
 
     # Fetches a wrapped paginated resource, returning wrapper fields + lazy paginated items.
     # @param path [String] URL path (without account prefix)
     # @param key [String] the key containing the array of paginated items
     # @param params [Hash] query parameters
-    # @return [Hash] wrapper fields merged with key => Enumerator of all items
-    def paginate_wrapped(path, key:, params: {}, operation: nil)
-      @parent.http.paginate_wrapped(account_path(path), key: key, params: params, operation: operation)
+    # @param max_items [Integer, nil] cap on items yielded across pages;
+    #   nil or non-positive means no cap
+    # @return [Hash] wrapper fields merged with key => ListEnumerator of all items
+    def paginate_wrapped(path, key:, params: {}, operation: nil, max_items: nil)
+      @parent.http.paginate_wrapped(account_path(path), key: key, params: params, operation: operation, \
+        max_items: max_items)
     end
 
     # Downloads file content from any API-routable download URL.
@@ -267,8 +275,9 @@ module Basecamp
         rewritten.port = base.port
         rewritten_url = rewritten.to_s
 
-        # Hop 1: Authenticated API request (no retry, captures redirect)
-        response = http.get_no_retry(rewritten_url)
+        # Hop 1: Authenticated API request under the SPEC §14 hop-1 retry
+        # policy (captures redirect; every attempt is authenticated)
+        response = http.get_download(rewritten_url)
 
         result = case response.status
         when 301, 302, 303, 307, 308
@@ -391,6 +400,16 @@ module Basecamp
       service(:documents) { Services::DocumentsService.new(self) }
     end
 
+    # @return [Services::CloudFilesService]
+    def cloud_files
+      service(:cloud_files) { Services::CloudFilesService.new(self) }
+    end
+
+    # @return [Services::GoogleDocumentsService]
+    def google_documents
+      service(:google_documents) { Services::GoogleDocumentsService.new(self) }
+    end
+
     # @return [Services::UploadsService]
     def uploads
       service(:uploads) { Services::UploadsService.new(self) }
@@ -486,6 +505,11 @@ module Basecamp
       service(:bookmarks) { Services::BookmarksService.new(self) }
     end
 
+    # @return [Services::FoldersService]
+    def folders
+      service(:folders) { Services::FoldersService.new(self) }
+    end
+
     # @return [Services::DraftsService]
     def drafts
       service(:drafts) { Services::DraftsService.new(self) }

data/lib/basecamp/config.rb

@@ -45,6 +45,75 @@ module Basecamp
     DEFAULT_MAX_JITTER = 0.1
     DEFAULT_MAX_PAGES = 10_000
 
+    # Ceiling on the backoff term (SPEC §7, "Backoff Ceiling"), in seconds.
+    # Jitter is added after the clamp, so the longest single backoff sleep is
+    # this plus +max_jitter+.
+    MAX_BACKOFF_DELAY = 30.0
+
+    # Smallest exponent +e+ with <tt>base_delay * 2**e >= MAX_BACKOFF_DELAY</tt>.
+    #
+    # Derived from the *configured* base rather than assumed. A fixed exponent
+    # cap plus a trailing +min(..., MAX_BACKOFF_DELAY)+ looks equivalent and is
+    # not: for a small enough base the capped product never reaches the ceiling,
+    # so the delay plateaus below it forever. At +base_delay = 1e-30+ a cap of
+    # 64 pins every attempt from 65 on at ~1.84e-11s — a tight retry loop, which
+    # is the failure SPEC §7's ceiling exists to prevent, not an instance of it.
+    #
+    # Computed in the LOG domain rather than as
+    # <tt>MAX_BACKOFF_DELAY / base_delay</tt>. That ratio coerces to
+    # +Float::INFINITY+ for any base below ~1.67e-307, and falling back to a
+    # fixed 1023 then saturates *early*: +base_delay = 1e-307+ reaches only
+    # ~8.99s at exponent 1023, so returning the 30s ceiling there overstates the
+    # specified term instead of tracking it. The log form has no such cliff, so
+    # the numeric backstop is gone entirely rather than merely made rarer.
+    #
+    # @param base_delay [Float] initial backoff delay in seconds, strictly positive
+    # @return [Integer] the exponent at which the term reaches the ceiling
+    def self.saturating_exponent(base_delay)
+      # log2 is correctly rounded but the subtraction is not, so the estimate can
+      # land one either side of the true boundary. Both corrections are bounded
+      # and evaluate the term with Math.ldexp, which scales directly and never
+      # forms 2**e.
+      exponent = [ (Math.log2(MAX_BACKOFF_DELAY) - Math.log2(base_delay)).ceil, 0 ].max
+      exponent -= 1 while exponent > 0 && Math.ldexp(base_delay, exponent - 1) >= MAX_BACKOFF_DELAY
+      exponent += 1 while Math.ldexp(base_delay, exponent) < MAX_BACKOFF_DELAY
+      exponent
+    end
+
+    # Exponential backoff for a 1-based attempt, saturating at MAX_BACKOFF_DELAY.
+    #
+    # The clamp is load-bearing rather than defensive. Ruby's +**+ promotes
+    # instead of overflowing, so +base_delay * (2**(attempt - 1))+ on a long
+    # failure streak coerces to +Float::INFINITY+ — and +sleep(Float::INFINITY)+
+    # never returns. A retry that never happens is not backoff.
+    #
+    # The exponent is compared against the point where the term reaches the
+    # ceiling *before* the power is evaluated, so no intermediate leaves the
+    # Float range and the term saturates AT the ceiling for every positive base
+    # — the same contract Go, Kotlin and Swift get from comparing their
+    # multiplier against <tt>MAX_BACKOFF_DELAY / base</tt> before multiplying.
+    #
+    # Below that point the term is scaled with +Math.ldexp+, which computes
+    # <tt>base * 2**e</tt> directly. +2**e+ would be an unbounded Integer that
+    # coerces to +Float::INFINITY+ long before the *product* leaves the Float
+    # range, which is what forced the fixed cap this replaces.
+    #
+    # @param base_delay [Float] initial backoff delay in seconds
+    # @param attempt [Integer] 1-based attempt number
+    # @return [Float] the backoff term in seconds
+    def self.saturating_backoff(base_delay, attempt)
+      if base_delay <= 0
+        0.0
+      else
+        exponent = [ attempt - 1, 0 ].max
+        if exponent >= saturating_exponent(base_delay)
+          MAX_BACKOFF_DELAY
+        else
+          [ Math.ldexp(base_delay, exponent), MAX_BACKOFF_DELAY ].min.to_f
+        end
+      end
+    end
+
     # Creates a new configuration with the given options.
     #
     # @param base_url [String] API base URL