basecamp-sdk 0.25.0 → 0.26.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7713550a3bc2d6b5dd732e3bdadb679d5016316e9f4004677c028a30daa65371
-  data.tar.gz: 71b74a2b499c484f245669d9b317df4f826c799f2d2bbda0cce140a75b22884f
+  metadata.gz: 1fd42c71ec94ed3fca5d41b7f015309154da9cba442bd5d7e1a4daa41fcc47f7
+  data.tar.gz: 38b36b58f82eb91498ec501a1d497ea18210ad07a7f4548820350a3f69c08724
 SHA512:
-  metadata.gz: a5f430f32c8ef3e13f0b3690ec31223bc942f06bc907708fe33fbfa84b99a86dcfe56a2734ef0e8224f5cfdfdc41ce4c28703e8321c6ba88330bba4bedf775f0
-  data.tar.gz: 834ea9c748c9d64ce67089e765875bf8c6c56a52ce0d895629b1c02f4d6e2acbdcb63b566a563c19823ce1c3199016b02fba3c92136bbbd5cb67cf6d950a0744
+  metadata.gz: 89dd7bc9af9f11a0365f768ffec3a6335b801f4278834dfadbbfe5963046f4da5f33bece26b8b112798896128e2def06c405d31f04b7f07b29e7432a384b9d83
+  data.tar.gz: 716839ec940b554a08f9049ec03caa88090e7965575dd29567545a38e04f8cd46176daf2de2882df079c32684f339e1b4c7ad09be523e0840854b0e0240919c3

data/README.md

@@ -348,6 +348,7 @@ The SDK provides the full account-scoped service set documented in SPEC §5. The
 | `card_columns` | Card table columns |
 | `card_steps` | Card workflow steps |
 | `subtasks` | Subtasks (checklist items) on to-dos and cards |
+| `pings` | Pings (direct and group chats) |
 | `wormholes` | Card table wormholes (cross-project moves) |
 | `lineup` | Card lineup view |
 | `tools` | Project dock tools |

data/lib/basecamp/campfire_index.rb

@@ -8,12 +8,15 @@ module Basecamp
   # Candidates come from two sources, tried in order and each cached {TTL}
   # seconds:
   #
-  # 1. The bucket's project dock, whose "chat" tool is the project's Campfire:
-  #    one project read per bucket, and the answer for every line posted in a
-  #    project. Cached per bucket.
+  # 1. The bucket's own Campfire. For a project, its dock's "chat" tool: one
+  #    project read per bucket, and the answer for every line posted in a
+  #    project. For a bucket that is not a project, its Ping's Campfire, since
+  #    a Ping's bucket type is "Circle". Cached per bucket.
   # 2. The account-wide Campfire listing (BC3 has no per-bucket one), filtered
-  #    to the bucket, for buckets that are not projects or whose dock did not
-  #    hold the line. Cached per account, so a burst of lines costs one listing.
+  #    to the bucket, for buckets that are neither or whose own Campfire did not
+  #    hold the line. BC3 lists only dock-positioned Campfires there, so a
+  #    ping's is never in it. Cached per account, so a burst of lines costs one
+  #    listing.
   #
   # This class holds the caching only; the reads themselves are passed in as
   # blocks by +RecordingsExtensions+, so every request still goes through a
@@ -28,7 +31,7 @@ module Basecamp
   # buckets and accounts consulted within the last TTL, and never more than the
   # bound, whatever the Client has seen.
   class CampfireIndex
-    # How long a cached discovery source — a bucket's project dock, the
+    # How long a cached discovery source — a bucket's own Campfire, the
     # account's Campfire listing — is reused before it is read again.
     TTL = 600.0
 
@@ -40,12 +43,13 @@ module Basecamp
 
     # Caps the account-wide Campfire listing the fallback source reads. A
     # listing that overflows it is not cached and the call reports
-    # {CampfireDiscoveryIncompleteError}: the dock covers every project, so the
-    # listing only ever serves the leftover, and an account with more Campfires
-    # than this should not pay a full walk per TTL for it.
+    # {CampfireDiscoveryIncompleteError}: the bucket's own Campfire covers every
+    # project and every ping, so the listing only ever serves the leftover, and
+    # an account with more Campfires than this should not pay a full walk per
+    # TTL for it.
     MAX_LISTING = 1000
 
-    # Bounds each cache's entry count. The dock cache holds one snapshot per
+    # Bounds each cache's entry count. The bucket cache holds one snapshot per
     # bucket consulted within the TTL: a connector listening across every
     # project an agent can see touches hundreds of buckets, not thousands, and a
     # snapshot is a handful of ids, so this is generous headroom at a few
@@ -75,12 +79,13 @@ module Basecamp
       @listings = TTLCache.new(ttl: TTL, floor: MIN_REFRESH, max_items: MAX_ITEMS, clock: clock)
     end
 
-    # The Campfire ids a bucket's project dock names.
+    # The Campfire ids a bucket's own source names: a project's dock, or a
+    # Ping's room.
     #
     # @param account_id [String]
     # @param bucket_id [Integer]
     # @param refresh [Boolean] re-read a cached snapshot older than {MIN_REFRESH}
-    # @yieldreturn [Array<Integer>] the dock's Campfire ids
+    # @yieldreturn [Array<Integer>] the bucket's own Campfire ids
     # @return [SourceRead]
     def dock_campfires(account_id:, bucket_id:, refresh: false, &load)
       hit = @docks.get([ account_id, bucket_id ], refresh: refresh, &load)
@@ -92,7 +97,8 @@ module Basecamp
     #
     # It exists so a caller can consult what the source already holds before
     # deciding whether to pay for the listing fetch — the expensive, slow
-    # request, which the dock (including its refresh) should get to pre-empt.
+    # request, which the bucket's own source (including its refresh) should get
+    # to pre-empt.
     #
     # @param account_id [String]
     # @param bucket_id [Integer]

data/lib/basecamp/client.rb

@@ -612,6 +612,11 @@ module Basecamp
       service(:subtasks) { Services::SubtasksService.new(self) }
     end
 
+    # @return [Services::PingsService]
+    def pings
+      service(:pings) { Services::PingsService.new(self) }
+    end
+
     # @return [Services::AccountService]
     def account
       service(:account) { Services::AccountService.new(self) }

data/lib/basecamp/generated/metadata.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://basecamp.com/schemas/sdk-metadata.json",
   "version": "1.0.0",
-  "generated": "2026-10-15T16:04:42Z",
+  "generated": "2026-10-19T21:23:14Z",
   "operations": {
     "GetAccount": {
       "retry": {
@@ -78,6 +78,20 @@
         ]
       }
     },
+    "UpdateBoost": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      },
+      "idempotent": {
+        "natural": true
+      }
+    },
     "DeleteBoost": {
       "retry": {
         "maxAttempts": 3,
@@ -919,6 +933,28 @@
         "maxPageSize": 50
       }
     },
+    "ListPings": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
+    "CreatePing": {
+      "retry": {
+        "maxAttempts": 2,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "ListPingablePeople": {
       "retry": {
         "maxAttempts": 3,
@@ -935,6 +971,17 @@
         "maxPageSize": 50
       }
     },
+    "GetPing": {
+      "retry": {
+        "maxAttempts": 3,
+        "baseDelayMs": 1000,
+        "backoff": "exponential",
+        "retryOn": [
+          429,
+          503
+        ]
+      }
+    },
     "GetClientApproval": {
       "retry": {
         "maxAttempts": 3,
@@ -3730,6 +3777,9 @@
     "CreateMessage": [
       "creator"
     ],
+    "CreatePing": [
+      "people.[]"
+    ],
     "CreateQuestion": [
       "creator"
     ],
@@ -4077,6 +4127,9 @@
       "events.[].creator",
       "person"
     ],
+    "GetPing": [
+      "people.[]"
+    ],
     "GetProgressReport": [
       "[].attachments.[].creator",
       "[].creator"
@@ -4251,6 +4304,9 @@
     "ListPingablePeople": [
       "[]"
     ],
+    "ListPings": [
+      "[].people.[]"
+    ],
     "ListProjectPeople": [
       "[]"
     ],
@@ -4340,6 +4396,9 @@
     "Subscribe": [
       "subscribers.[]"
     ],
+    "UpdateBoost": [
+      "booster"
+    ],
     "UpdateCard": [
       "assignees.[]",
       "completer",

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

@@ -16,6 +16,16 @@ module Basecamp
         end
       end
 
+      # Replace the content of a boost. Only the boost's creator may update it: an
+      # @param boost_id [Integer] boost id ID
+      # @param content [String] content
+      # @return [Hash] response data
+      def update_boost(boost_id:, content:)
+        with_operation(service: "boosts", operation: "update_boost", is_mutation: true, resource_id: boost_id) do
+          http_put("/boosts/#{boost_id}", body: compact_params(content: content)).json(operation: "UpdateBoost")
+        end
+      end
+
       # Delete a boost
       # @param boost_id [Integer] boost id ID
       # @return [void]

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

@@ -29,9 +29,10 @@ module Basecamp
         end
       end
 
-      # Move a card to a different column
+      # Move a card to any column in its project, including on another card table there, or through a linked wormhole to another project (queued: the card gets a new id, and position, if sent, must still be positive but doesn't set placement).
       # @param card_id [Integer] card id ID
-      # @param column_id [Integer] column id
+      # @param column_id [Integer] Any column in the card's project, on this or another card table, or a
+      #   wormhole id to send the card to another project.
       # @param position [Integer, nil] 1-indexed position within the destination column. Defaults to 1 (top).
       # @return [void]
       def move(card_id:, column_id:, position: nil)

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

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module Basecamp
+  module Services
+    # Service for Pings operations
+    #
+    # @generated from OpenAPI spec
+    class PingsService < BaseService
+
+      # Get Pings: the caller's active Pings that have a line in them, most
+      # @return [Array<Hash>] response data
+      def list()
+        with_operation(service: "pings", operation: "list", is_mutation: false) do
+          http_get("/circles.json", operation: "ListPings").json(operation: "ListPings")
+        end
+      end
+
+      # Create a Ping with people, or return the one that already holds exactly
+      # @param user_ids [Array] Person ids of the people to ping. People the caller cannot reach are
+      #   dropped.
+      # @param new_group [Boolean, nil] Create a new group even when a Ping with exactly these people exists.
+      # @return [Hash] response data
+      def create(user_ids:, new_group: nil)
+        with_operation(service: "pings", operation: "create", is_mutation: true) do
+          http_post("/circles.json", body: compact_params(user_ids: user_ids, new_group: new_group)).json(operation: "CreatePing")
+        end
+      end
+
+      # Get a Ping by its id, which is its bucket's id.
+      # @param ping_id [Integer] A Ping's id is the id of the bucket that holds it (the bucket type is
+      #   "Circle", which is also the wire path), so the `bucket.id` a Ping's
+      #   recordings carry is the id GetPing takes.
+      # @return [Hash] response data
+      def get(ping_id:)
+        with_operation(service: "pings", operation: "get", is_mutation: false, resource_id: ping_id) do
+          http_get("/circles/#{ping_id}", operation: "GetPing").json(operation: "GetPing")
+        end
+      end
+    end
+  end
+end

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

@@ -7,7 +7,7 @@ module Basecamp
     # @generated from OpenAPI spec
     class WormholesService < BaseService
 
-      # Update a wormhole's destination column
+      # Point a card table's wormhole, its shortcut for sending cards to another card table, at a different destination column
       # @param bucket_id [Integer] bucket id ID
       # @param wormhole_id [Integer] wormhole id ID
       # @param destination_recording_id [Integer] Id of the new destination column (on another accessible card table).
@@ -18,7 +18,7 @@ module Basecamp
         end
       end
 
-      # Delete a wormhole
+      # Permanently delete a card table's wormhole, the shortcut that sends cards to another card table.
       # @param bucket_id [Integer] bucket id ID
       # @param wormhole_id [Integer] wormhole id ID
       # @return [void]
@@ -29,7 +29,7 @@ module Basecamp
         end
       end
 
-      # Create a wormhole linking this card table to a column on another card table.
+      # Add a wormhole to a card table: a standing shortcut that sends cards to a column on another card table, usually in another project.
       # @param bucket_id [Integer] bucket id ID
       # @param card_table_id [Integer] card table id ID
       # @param destination_recording_id [Integer] Id of the destination column (on another accessible card table) to link to.

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-10-15T16:04:42Z
+# Generated: 2026-10-19T21:23:14Z
 
 require "json"
 require "time"
@@ -3208,6 +3208,84 @@ module Basecamp
       end
     end
 
+    # Ping
+    class Ping
+      include TypeHelpers
+      attr_accessor :app_url, :avatar_url, :bookmark_url, :created_at, :id, :links, :named, :people, :room_url, :title, :updated_at, :url, :edit_title_url, :image_url
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[app_url avatar_url bookmark_url created_at id links named people room_url title updated_at url].freeze
+      end
+
+      def initialize(data = {})
+        @app_url = data["app_url"]
+        @avatar_url = data["avatar_url"]
+        @bookmark_url = data["bookmark_url"]
+        @created_at = parse_datetime(data["created_at"])
+        @id = parse_integer(data["id"])
+        @links = parse_type(data["links"], "PingLinks")
+        @named = parse_boolean(data["named"])
+        @people = parse_array(data["people"], "Person")
+        @room_url = data["room_url"]
+        @title = data["title"]
+        @updated_at = parse_datetime(data["updated_at"])
+        @url = data["url"]
+        @edit_title_url = data["edit_title_url"]
+        @image_url = data["image_url"]
+      end
+
+      def to_h
+        {
+          "app_url" => @app_url,
+          "avatar_url" => @avatar_url,
+          "bookmark_url" => @bookmark_url,
+          "created_at" => @created_at,
+          "id" => @id,
+          "links" => @links,
+          "named" => @named,
+          "people" => @people,
+          "room_url" => @room_url,
+          "title" => @title,
+          "updated_at" => @updated_at,
+          "url" => @url,
+          "edit_title_url" => @edit_title_url,
+          "image_url" => @image_url,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
+    # PingLinks
+    class PingLinks
+      include TypeHelpers
+      attr_accessor :files, :lines
+
+      # @return [Array<Symbol>]
+      def self.required_fields
+        %i[files lines].freeze
+      end
+
+      def initialize(data = {})
+        @files = data["files"]
+        @lines = data["lines"]
+      end
+
+      def to_h
+        {
+          "files" => @files,
+          "lines" => @lines,
+        }.compact
+      end
+
+      def to_json(*args)
+        to_h.to_json(*args)
+      end
+    end
+
     # Preferences
     class Preferences
       include TypeHelpers

data/lib/basecamp/services/recordings_extensions.rb

@@ -49,6 +49,8 @@ module Basecamp
         "The recording summary reads this field to decide what the recording is and which " \
         "project it belongs to, so a value of the wrong type cannot be used."
 
+      ROOM_URL_CAMPFIRE = %r{/chats/([0-9]+)(?:\.json)?\z}
+
       DISCOVERY_HINT =
         "The recording summary reads this field to decide which Campfires a chat line could " \
         "be in, so a value of the wrong type cannot be used."
@@ -133,10 +135,10 @@ module Basecamp
       RICH_TEXT_CHAT_LINE_TYPES = [ "Chat::Lines::RichText", "Chat::Lines::Integration" ].freeze
 
       # Bounds how many Campfires one {#summarize} call tries, across both
-      # discovery sources and the refresh. A project has one Campfire and a
-      # handful of pings; a bucket past this bound is not a shape BC3 produces,
-      # and the call reports {Basecamp::CampfireDiscoveryIncompleteError} rather
-      # than calling the rest absent.
+      # discovery sources and the refresh. A project or a Ping has one
+      # Campfire; a bucket past this bound is not a shape BC3 produces, and the
+      # call reports {Basecamp::CampfireDiscoveryIncompleteError} rather than
+      # calling the rest absent.
       MAX_CAMPFIRE_CANDIDATES = 50
 
       # Where #project leaves the validated bucket id for the cross-bucket
@@ -1029,14 +1031,14 @@ module Basecamp
         account_id = @client.account_id
         search = ChatLineSearch.new(campfires: @client.campfires, line_id: line_id)
 
-        # Pass 1: what the sources already hold — the dock (read if it must be),
-        # then the listing only if it is cached. A listing fetch is the
-        # expensive, slow request, and it is not made until the dock — including
-        # its refresh — has had its say, so a listing that is down, over its cap,
-        # or stalled never stands between a project's line and the one project
-        # read that finds it.
+        # Pass 1: what the sources already hold — the bucket's own Campfire
+        # (read if it must be), then the listing only if it is cached. A listing
+        # fetch is the expensive, slow request, and it is not made until the
+        # bucket's own source — including its refresh — has had its say, so a
+        # listing that is down, over its cap, or stalled never stands between a
+        # project's line and the one project read that finds it.
         dock = index.dock_campfires(account_id: account_id, bucket_id: bucket_id) do
-          dock_campfire_ids(bucket_id)
+          bucket_campfire_ids(bucket_id)
         end
         found = search.try(dock.ids)
         return found if found
@@ -1048,7 +1050,7 @@ module Basecamp
           return found if found
         end
 
-        # Pass 2: re-read the dock if it was served from cache (the floor may
+        # Pass 2: re-read the bucket's own source if it was served from cache (the floor may
         # decline), then fetch or refresh the listing. Whatever comes back is the
         # current snapshot of that source, whoever loaded it — another caller may
         # have populated or refreshed it in the meantime — so it always replaces
@@ -1071,7 +1073,7 @@ module Basecamp
 
         if search.budget_left? && dock.cached?
           again = index.dock_campfires(account_id: account_id, bucket_id: bucket_id, refresh: true) do
-            dock_campfire_ids(bucket_id)
+            bucket_campfire_ids(bucket_id)
           end
           refreshed = true if again.fetched > dock.fetched || !again.cached?
           dock = again
@@ -1119,17 +1121,52 @@ module Basecamp
         )
       end
 
-      # The Campfire ids a bucket's project dock names. A bucket that is not a
-      # project (a 404 on the project read) has none; any other failure of the
-      # read is raised.
-      def dock_campfire_ids(bucket_id)
+      # The bucket's own Campfire ids: a project's dock "chat" tools or, when
+      # the project read 404s, its Ping's Campfire. A bucket that is neither
+      # has none; any other failure of either read is raised, so a 403 "Pings
+      # have been disabled" is a failed read and never an unresolved line.
+      def bucket_campfire_ids(bucket_id)
         project = begin
           @client.projects.get(project_id: bucket_id)
+        rescue NotFoundError
+          return ping_campfire_ids(bucket_id)
+        end
+
+        dock_campfire_ids(read_record(project))
+      end
+
+      # The one Campfire a Ping holds, named by its +room_url+. A Ping whose
+      # room_url names no Campfire has none.
+      def ping_campfire_ids(bucket_id)
+        ping = begin
+          @client.pings.get(ping_id: bucket_id)
         rescue NotFoundError
           return []
         end
 
-        project = read_record(project)
+        room_url = read_record(ping)["room_url"]
+        return [] if room_url.nil?
+
+        unless room_url.is_a?(String)
+          raise malformed_response("the Ping's \"room_url\" is #{MergeSafe.describe(room_url)}, not a string",
+            hint: DISCOVERY_HINT)
+        end
+
+        id = campfire_id_from_room_url(room_url)
+        id ? [ id ] : []
+      end
+
+      # Strict: the path must end in +/chats/{digits}+, optionally +.json+, so a
+      # Campfire's lines, a to-do or a garbled URL name no Campfire.
+      def campfire_id_from_room_url(room_url)
+        match = ROOM_URL_CAMPFIRE.match(room_url.split(/[?#]/, 2).first)
+        return nil if match.nil?
+
+        id = Ids.bounded_decimal(match[1], signed: false)
+        id.is_a?(Integer) && id.positive? ? id : nil
+      end
+
+      def dock_campfire_ids(project)
         dock = project["dock"]
         # An absent dock is genuinely none — a project need not have one, and the
         # reference reads its zero value. Anything else that is not an array is a

data/lib/basecamp/version.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
 module Basecamp
-  VERSION = "0.25.0"
-  API_VERSION = "2026-09-15"
+  VERSION = "0.26.0"
+  API_VERSION = "2026-10-19"
 end

data/scripts/generate-services.rb

@@ -83,6 +83,7 @@ class ServiceGenerator
     'ClientFeatures' => 'ClientFeatures',
     'Boosts' => 'Boosts',
     'Subtasks' => 'Subtasks',
+    'Pings' => 'Pings',
     'Untagged' => 'Miscellaneous'
   }.freeze
 
@@ -363,7 +364,7 @@ class ServiceGenerator
     lineupmarker clientapproval clientapprovals clientcorrespondence
     clientcorrespondences clientreply clientreplies forwardreply
     forwardreplies campfireline campfirelines todolistgroup todolistgroups
-    todolistorgroup uploadversions hillchart hillcharts subtask subtasks
+    todolistorgroup uploadversions hillchart hillcharts subtask subtasks ping pings
     wormhole wormholes
   ].freeze
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: basecamp-sdk
 version: !ruby/object:Gem::Version
-  version: 0.25.0
+  version: 0.26.0
 platform: ruby
 authors:
 - Basecamp
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-10-15 00:00:00.000000000 Z
+date: 2026-10-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -218,6 +218,7 @@ files:
 - lib/basecamp/generated/services/my_notes_service.rb
 - lib/basecamp/generated/services/my_notifications_service.rb
 - lib/basecamp/generated/services/people_service.rb
+- lib/basecamp/generated/services/pings_service.rb
 - lib/basecamp/generated/services/projects_service.rb
 - lib/basecamp/generated/services/recordings_service.rb
 - lib/basecamp/generated/services/reports_service.rb