Ruby retry docs from ground truth; TS docstring examples typecheck

[jeremy]

Fixes #510. Fixes #511.

Ruby — Retry Behavior rewritten from the transport's ground truth

The old section was wrong twice over, both proven by driving the real request_with_retry loop with only single_request stubbed:

• "Retryable errors: 429, 502, 503, 504" — but the loop keys off retryable?, which is true for 500 and every other 5xx. Proof: a stubbed 500 on GET under max_retries: 3 produced exactly 3 invocations.
• max_retries documented as "max retry attempts" — it is the total attempt budget. Proof: Config.new(max_retries: 0) → zero HTTP calls, raising Basecamp::ApiError: Request failed after 0 attempts.

The rewrite also covers the contract corners the old text ignored: GET-only scope with the raw-path carve-outs; the read-timeout exception (Faraday maps read timeouts to Faraday::TimeoutError < ServerError, caught ahead of the NetworkError rescue and classified as a status-less, retryable? == false ApiError — proven empirically: stubbed read timeout → 1 attempt, no retry, vs ConnectionFailed → NetworkError, 3 attempts); uncapped exponential backoff; Retry-After only via 429; the one-shot 401 refresh replay for all methods outside the budget; per-operation retry metadata being inert in Ruby; and retryable? as the actual transport predicate (the inverse of Python's "classification is only a hint" framing). Config comment, options table, env-var table (adding the missing BASECAMP_TIMEOUT/BASECAMP_MAX_RETRIES rows), and the same misstatements in config.rb's doc comments all aligned.

Ruby suite: 908 runs, 2079 assertions, 0 failures; rubocop clean.

TypeScript — docstring examples pass strict typecheck

fetchAllPages/paginateAll @example blocks used bare (r) => r.json() — Promise<unknown> under Node fetch types, failing the parse callback's Promise<T[]> in any strict/NodeNext project configured like this repo (the defect #507 fixed in the README, still present in source). Red proof, the extracted examples verbatim under the repo-shaped harness:

error TS2322: Type 'Promise<unknown>' is not assignable to type 'Promise<unknown[]>'.

Green with the README's proven form (r) => r.json() as Promise<any[]>; tsc --noEmit clean; vitest 979 passed (local count).

These are the only two bare r.json() docstring sites in typescript/src (verified by grep — everything else is real code operating under the SDK's own types).

---

Summary by cubic

Updates Ruby retry docs to match the actual transport behavior and fixes TypeScript pagination examples to pass strict typecheck. Clarifies max_retries semantics to prevent misleading guidance.

• Bug Fixes
  • Ruby docs: Rewrite Retry Behavior to reflect transport ground truth — GET-only; retryable?-based (429, all 5xx, network); no retry on read timeouts/4xx; max_retries = total attempts (0 sends none); exponential backoff with jitter and 429 Retry-After; one-shot 401 refresh; raw upload/download carve-outs; per-operation retry metadata ignored. Also align config.rb comments and README tables, adding BASECAMP_TIMEOUT and BASECAMP_MAX_RETRIES.
  • TypeScript: Make fetchAllPages/paginateAll @example blocks typecheck by casting r.json() to Promise<any[]>.

^{Written for commit 572bce9. Summary will update on new commits.}

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.