basecamp-sdk 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 333309f03879b5b93ba66a1b6da556fefa44e67608544dadfdb27cac0ade7a6e
-  data.tar.gz: a2601804437fb844bb148ea53d458c1003dc2e96faaabda5f47abcd489b9feea
+  metadata.gz: 77ea8d483dab96eeb6721a83f11100e5b46ffd1901d4607f4c1dc1b882fb34c9
+  data.tar.gz: f2e1946f8a21e6620f051cb2ea6c74f6374cd8d6ba1074ab7264960acd8528c5
 SHA512:
-  metadata.gz: 7308e4342b71c0f4e577f7010d3f64963705a2b42e638174a79689a01af17faf9f49ab58de1eb983f3071d3f94201cad17906ce616495e886c29dbda2389677d
-  data.tar.gz: 6ebf54b146a9fa683832100267fadb3f7f6b04cc7582e59ad763640d6a885817aac0d227f1c65240e022b9c0cdbd62e5d4712a2de5a094a5163e0414edb269b5
+  metadata.gz: 919b6403677541f344409a96208f1e4e3a20a7cee39ba078b72847d7fb8359af418a3959901cbe6e09835a51b361a5c0d1f48aaa0c18aa4e3e68cec7e2b7051b
+  data.tar.gz: 504c56f9a01cdcc29876969e485f78fbc19d8d6b74849f871ca01406ad1078d58f52caac079ef5778f52f39a6694b63a47bd1264968212c4c21bfd9ad6f1743c

data/lib/basecamp/client.rb

@@ -208,6 +208,15 @@ module Basecamp
       @parent.http.paginate_key(account_path(path), key: key, params: params, &)
     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: {})
+      @parent.http.paginate_wrapped(account_path(path), key: key, params: params)
+    end
+
     # @!group Services
 
     # @return [Services::ProjectsService]

data/lib/basecamp/generated/metadata.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://basecamp.com/schemas/sdk-metadata.json",
   "version": "1.0.0",
-  "generated": "2026-03-09T21:06:11Z",
+  "generated": "2026-03-11T02:58:58Z",
   "operations": {
     "CreateAttachment": {
       "retry": {
@@ -1107,6 +1107,11 @@
           429,
           503
         ]
+      },
+      "pagination": {
+        "style": "link",
+        "totalCountHeader": "X-Total-Count",
+        "maxPageSize": 50
       }
     },
     "GetAnswer": {
@@ -1544,6 +1549,11 @@
           429,
           503
         ]
+      },
+      "pagination": {
+        "style": "link",
+        "totalCountHeader": "X-Total-Count",
+        "maxPageSize": 50
       }
     },
     "CreateTimesheetEntry": {
@@ -1676,6 +1686,11 @@
           429,
           503
         ]
+      },
+      "pagination": {
+        "style": "link",
+        "totalCountHeader": "X-Total-Count",
+        "maxPageSize": 50
       }
     },
     "GetScheduleEntry": {

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

@@ -47,8 +47,8 @@ module Basecamp
       # @param person_id [Integer] person id ID
       # @return [Hash] response data
       def person_progress(person_id:)
-        with_operation(service: "reports", operation: "person_progress", is_mutation: false, resource_id: person_id) do
-          http_get("/reports/users/progress/#{person_id}").json
+        wrap_paginated_wrapped(key: "events", service: "reports", operation: "person_progress", is_mutation: false, resource_id: person_id) do
+          paginate_wrapped("/reports/users/progress/#{person_id}.json", key: "events")
         end
       end
     end

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

@@ -12,10 +12,11 @@ module Basecamp
       # @param from [String, nil] from
       # @param to [String, nil] to
       # @param person_id [Integer, nil] person id
-      # @return [Hash] response data
+      # @return [Enumerator<Hash>] paginated results
       def for_project(project_id:, from: nil, to: nil, person_id: nil)
-        with_operation(service: "timesheets", operation: "for_project", is_mutation: false, project_id: project_id) do
-          http_get("/projects/#{project_id}/timesheet.json", params: compact_params(from: from, to: to, person_id: person_id)).json
+        wrap_paginated(service: "timesheets", operation: "for_project", is_mutation: false, project_id: project_id) do
+          params = compact_params(from: from, to: to, person_id: person_id)
+          paginate("/projects/#{project_id}/timesheet.json", params: params)
         end
       end
 
@@ -24,10 +25,11 @@ module Basecamp
       # @param from [String, nil] from
       # @param to [String, nil] to
       # @param person_id [Integer, nil] person id
-      # @return [Hash] response data
+      # @return [Enumerator<Hash>] paginated results
       def for_recording(recording_id:, from: nil, to: nil, person_id: nil)
-        with_operation(service: "timesheets", operation: "for_recording", is_mutation: false, resource_id: recording_id) do
-          http_get("/recordings/#{recording_id}/timesheet.json", params: compact_params(from: from, to: to, person_id: person_id)).json
+        wrap_paginated(service: "timesheets", operation: "for_recording", is_mutation: false, resource_id: recording_id) do
+          params = compact_params(from: from, to: to, person_id: person_id)
+          paginate("/recordings/#{recording_id}/timesheet.json", params: params)
         end
       end
 

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-03-09T21:06:11Z
+# Generated: 2026-03-11T02:58:58Z
 
 require "json"
 require "time"

data/lib/basecamp/http.rb

@@ -172,6 +172,72 @@ module Basecamp
       end
     end
 
+    # Fetches a wrapped paginated resource, returning wrapper fields + lazy paginated items.
+    # Use this for endpoints that return {wrapper_field: ..., key: [items]} on every page.
+    # @param path [String] initial URL path
+    # @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: {})
+      base_url = build_url(path)
+
+      @hooks.on_paginate(base_url, 1)
+      first_response = get(base_url, params: params)
+      Security.check_body_size!(first_response.body, Security::MAX_RESPONSE_BODY_BYTES)
+
+      begin
+        first_data = JSON.parse(first_response.body)
+      rescue JSON::ParserError => e
+        raise Basecamp::APIError.new(
+          "Failed to parse paginated response (page 1): #{Security.truncate(e.message)}"
+        )
+      end
+
+      wrapper = first_data.reject { |k, _| k == key }
+      first_items = first_data[key] || []
+
+      events = Enumerator.new do |yielder|
+        first_items.each { |item| yielder << item }
+
+        next_link = parse_next_link(first_response.headers["Link"])
+        url = base_url
+        page = 1
+
+        while next_link && page < @config.max_pages
+          page += 1
+          next_url = Security.resolve_url(url, next_link)
+
+          unless Security.same_origin?(next_url, base_url)
+            raise Basecamp::APIError.new(
+              "Pagination Link header points to different origin: " \
+              "#{Security.truncate(next_url)}"
+            )
+          end
+
+          @hooks.on_paginate(next_url, page)
+          response = get(next_url)
+          Security.check_body_size!(response.body, Security::MAX_RESPONSE_BODY_BYTES)
+
+          begin
+            data = JSON.parse(response.body)
+          rescue JSON::ParserError => e
+            raise Basecamp::APIError.new(
+              "Failed to parse paginated response (page #{page}): " \
+              "#{Security.truncate(e.message)}"
+            )
+          end
+
+          items = data[key] || []
+          items.each { |item| yielder << item }
+
+          next_link = parse_next_link(response.headers["Link"])
+          url = next_url
+        end
+      end
+
+      wrapper.merge(key => events)
+    end
+
     private
 
     def build_faraday_client

data/lib/basecamp/services/base_service.rb

@@ -85,6 +85,43 @@ module Basecamp
         end
       end
 
+      # Wraps a wrapped-paginated operation with hooks.
+      # Fires on_operation_start eagerly (before page 1 fetch),
+      # on_operation_end when the events Enumerator completes/errors/breaks.
+      def wrap_paginated_wrapped(key:, service:, operation:, is_mutation: false, project_id: nil, resource_id: nil)
+        info = OperationInfo.new(
+          service: service, operation: operation,
+          is_mutation: is_mutation, project_id: project_id, resource_id: resource_id
+        )
+        hooks = @hooks
+        start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+        safe_hook { hooks.on_operation_start(info) }
+
+        begin
+          result = yield  # paginate_wrapped fetches page 1 here
+        rescue => e
+          duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+          safe_hook { hooks.on_operation_end(info, OperationResult.new(duration_ms: duration, error: e)) }
+          raise
+        end
+
+        inner_enum = result[key]
+        wrapped_enum = Enumerator.new do |yielder|
+          error = nil
+          begin
+            inner_enum.each { |item| yielder.yield(item) }
+          rescue => e
+            error = e
+            raise
+          ensure
+            duration = ((Process.clock_gettime(Process::CLOCK_MONOTONIC) - start) * 1000).round
+            safe_hook { hooks.on_operation_end(info, OperationResult.new(duration_ms: duration, error: error)) }
+          end
+        end
+
+        result.merge(key => wrapped_enum)
+      end
+
       # Invoke a hook callback, swallowing exceptions so hooks never break SDK behavior.
       def safe_hook
         yield
@@ -141,6 +178,11 @@ module Basecamp
       def paginate_key(...)
         @client.paginate_key(...)
       end
+
+      # Paginate a wrapped response extracting items from a specific key
+      def paginate_wrapped(...)
+        @client.paginate_wrapped(...)
+      end
     end
   end
 end

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
   API_VERSION = "2026-01-26"
 end

data/scripts/generate-services.rb

@@ -387,7 +387,8 @@ class ServiceGenerator
       returns_void: returns_void,
       returns_array: returns_array,
       is_mutation: http_method != 'GET',
-      has_pagination: !!operation['x-basecamp-pagination']
+      has_pagination: !!operation['x-basecamp-pagination'],
+      pagination_key: operation.dig('x-basecamp-pagination', 'key')
     }
   end
 
@@ -574,9 +575,14 @@ class ServiceGenerator
     end
 
     # Add @return tag
+    is_paginated = (op[:returns_array] || op[:has_pagination]) && !op[:pagination_key]
+    is_wrapped_paginated = op[:has_pagination] && op[:pagination_key]
+
     if op[:returns_void]
       lines << '      # @return [void]'
-    elsif op[:returns_array] || op[:has_pagination]
+    elsif is_wrapped_paginated
+      lines << '      # @return [Hash] response data'
+    elsif is_paginated
       lines << '      # @return [Enumerator<Hash>] paginated results'
     else
       lines << '      # @return [Hash] response data'
@@ -587,10 +593,15 @@ class ServiceGenerator
     # Build the path
     path_expr = build_path_expression(op)
 
-    is_paginated = op[:returns_array] || op[:has_pagination]
     hook_kwargs = build_hook_kwargs(op, service_name)
 
-    if is_paginated
+    if is_wrapped_paginated
+      pagination_key = op[:pagination_key]
+      lines << "        wrap_paginated_wrapped(key: \"#{pagination_key}\", #{hook_kwargs}) do"
+      body_lines = generate_wrapped_paginated_method_body(op, path_expr, pagination_key)
+      body_lines.each { |l| lines << "  #{l}" }
+      lines << '        end'
+    elsif is_paginated
       # wrap_paginated defers hooks to actual iteration time (lazy-safe)
       lines << "        wrap_paginated(#{hook_kwargs}) do"
       body_lines = generate_list_method_body(op, path_expr)
@@ -717,6 +728,20 @@ class ServiceGenerator
     lines
   end
 
+  def generate_wrapped_paginated_method_body(op, path_expr, pagination_key)
+    lines = []
+
+    if op[:query_params].any?
+      param_names = op[:query_params].map { |q| "#{to_snake_case(q[:name])}: #{to_snake_case(q[:name])}" }
+      lines << "        params = compact_params(#{param_names.join(', ')})"
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\", params: params)"
+    else
+      lines << "        paginate_wrapped(#{path_expr}, key: \"#{pagination_key}\")"
+    end
+
+    lines
+  end
+
   def generate_get_method_body(op, path_expr)
     lines = []
     http_method = op[:http_method].downcase

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-03-09 00:00:00.000000000 Z
+date: 2026-03-11 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday