basecradle 0.13.0 → 0.14.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6890e967dabc9e436aa26c23176989252913f567c1786b1f5ec3a57f9db825a1
-  data.tar.gz: 19db33d569829502555ea735d9a9c4eb59f7997cfefb74db7995c39c627e89f6
+  metadata.gz: e52bd37f68c6961351dde4657cb665f346548f20023d9372166333ff943529b0
+  data.tar.gz: f5725693ace3374348be8ef9771db763533d7526ff902ac7f029b3425e061137
 SHA512:
-  metadata.gz: b465e8f38d39746781b876d2bec7d4bc58eea8a93b39ede46f7b3553e52ea98402aa5de85a4274eef151a368289b06f5ddebd0cfbf8600f9bebfcd2320cf892b
-  data.tar.gz: 7c612778aa574a28d4ad4b52c1e40c1e37fc2b8edab358e94ad6f07233af6726307d3ca65ec7e94efb39133f1e26fc42e415476d4d409313dccaa79e856da425
+  metadata.gz: 0c2c1cb2a1b5d23214bb743a6be23f1756565696bb2cb807f7c1634fa0fc4c24a326ea862fcbac2d25ed78b8f41f3ee1c1017dea3ca025909345a78b81703058
+  data.tar.gz: 70618de428d28dfa790c95f278ddcd043062c0759efd30f1c277204f1704b031977560ada0c8e31ad35c5ac8957e9010c4be846696b2ab011b6fc4a1eae0c91c

data/CHANGELOG.md

@@ -9,6 +9,49 @@ section**. The newest heading is always the version `lib/basecradle/version.rb`
 a release writes its entry and its version in the same PR — and `test/changelog_test.rb`
 fails CI if the two ever disagree.
 
+## [0.14.0] - 2026-10-23
+
+A parity release. The first full SDK parity audit (basecradle#715) checked every issue
+ever filed on either SDK against the other's shipped code. This release brings over what
+the Python SDK had and this one did not, plus one behavior the founder ruled on.
+
+### Added
+
+- **The Dashboard's orientation blocks are typed**
+  ([#254](https://github.com/basecradle/basecradle-ruby/pull/254), mirroring
+  basecradle-python#188). `bc.me.environment.concepts_url` links the platform's
+  vocabulary. `bc.me.interaction.pagination` (a `BaseCradle::DashboardPagination`:
+  `summary`, `guide_url`) says how lists page and what is safe to checkpoint on.
+  `bc.me.interaction.tools` (a `BaseCradle::DashboardTools`: `summary`, `mapping_url`)
+  says that platform tools are thin wrappers over this same HTTP API. Both blocks read as
+  attributes, like every other section. They were previously reachable only as bare
+  Hashes through `[]`.
+- **The drift-guard checks error codes too**
+  ([#253](https://github.com/basecradle/basecradle-ruby/pull/253), mirroring
+  basecradle-python#265). Besides the spec's endpoints, `rake test:live` now reads the
+  API docs' Error Codes table and fails when the platform documents a code that has no
+  typed exception in `BaseCradle::CODE_TO_ERROR`. Without a typed exception, callers would
+  get a bare `BaseCradle::Error` for that code. The offline suite also pins its error
+  catalog to the registry, so a mapping removed, or added without a test, fails CI.
+
+### Changed
+
+- **`contact_message.add_note` appends the new note to `notes`**
+  ([#257](https://github.com/basecradle/basecradle-ruby/pull/257); founder ruling,
+  basecradle#715). It still returns the `BaseCradle::Note`. It now also appends that note
+  to the record's own `notes`, unless a note with the same `uuid` is already there, so you
+  no longer need to re-fetch the record to read it. This matches the Python SDK. Code that
+  appended the returned note by hand should stop doing so, or it will hold the note twice.
+- **Retry backoff is capped at 8 seconds**
+  ([#255](https://github.com/basecradle/basecradle-ruby/pull/255), mirroring
+  basecradle-python#107). With `max_retries:` set, the wait still doubles from 0.5s, but it
+  never exceeds `BaseCradle::Client::RETRY_MAX_DELAY` (8.0). Before this, the tenth retry
+  waited 256 seconds.
+- **Event Delivery is described as "outbound delivery", never "push"**
+  ([#256](https://github.com/basecradle/basecradle-ruby/pull/256), mirroring
+  basecradle-python#181). This is a wording change in the README and in the 0.4.0 entry
+  below; no behavior changes.
+
 ## [0.13.0] - 2026-10-23
 
 ### Added
@@ -593,7 +636,7 @@ enrichments come with them — but three things that worked on a `Hash` no longe
   header. The platform stores **at most one record per key** (scoped per timeline + author;
   per timeline for authorless webhook endpoints), so a replayed keyed create returns the
   **original record** — no duplicate record, no second **Event Delivery** event, no task
-  activation. (Event Delivery is the platform's *outbound* push through your integration;
+  activation. (Event Delivery is the platform's *outbound* delivery to your integration;
   the webhook endpoints named above are the *inbound* feature the SDK models — opposite
   directions, different features.) A key identifies one logical create: the same key with a
   different body still returns the original record. Keys never expire and never appear in a
@@ -687,6 +730,7 @@ the Python SDK's behavior in idiomatic Ruby. Zero runtime dependencies.
 - **Quality bars** — a README-as-tested-doc harness (every example runs against a mocked
   API) and a spec drift-guard (CI fails if the live API grows beyond the SDK).
 
+[0.14.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.14.0
 [0.13.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.13.0
 [0.12.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.12.0
 [0.11.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.11.0

data/README.md

@@ -175,7 +175,7 @@ inventing a value.
 
 ## Webhooks
 
-External services deliver into a timeline by POSTing to an endpoint's secret ingest URL. Each delivery becomes a readable event. This is the **inbound** direction — data arriving at BaseCradle. Its outbound counterpart is Event Delivery, the platform's push through your integration, which the SDK does not model.
+External services deliver into a timeline by POSTing to an endpoint's secret ingest URL. Each delivery becomes a readable event. This is the **inbound** direction — data arriving at BaseCradle. Its counterpart is Event Delivery, the platform's outbound delivery to your integration, which the SDK does not model.
 
 ```ruby
 require "basecradle"
@@ -258,7 +258,7 @@ A create can succeed on the server while its response is lost on the wire — re
 
 Keys are scoped **per timeline and per author** for all four resources — yours never collide with another peer's, and the same key on two timelines creates two records.
 
-Opt into automatic retries with `max_retries:`. It is off by default, and even when on it only re-sends what's safe: any read (`GET`) and any create that carries an `idempotency_key`. An **unkeyed** create is never retried — which is why the two features ship together.
+Opt into automatic retries with `max_retries:`. It is off by default, and even when on it only re-sends what's safe: any read (`GET`) and any create that carries an `idempotency_key`. An **unkeyed** create is never retried — which is why the two features ship together. Retries back off exponentially — 0.5s, 1s, 2s, … — capped at 8s between attempts.
 
 ```ruby
 require "basecradle"
@@ -387,8 +387,8 @@ bc.notes.each { |n| puts n.body }  # every note, across every subject, newest fi
 A contact message is a flat record with no `type`/`content` wrapper, so `message.uuid`
 is its identity. `set_status` changes the triage verdict in any direction (reopen with
 `"received"`). It updates the object you called it on and returns it. `add_note` returns
-the new `BaseCradle::Note` and leaves `message.notes` as it was fetched, so call
-`bc.contact_messages.get` again to read the record with the new note embedded. A note
+the new `BaseCradle::Note` and appends it to `message.notes`, unless a note with that
+`uuid` is already there. A note can never be edited or deleted afterwards. A note
 body is not idempotent, so `add_note` is never retried automatically.
 
 `data` is a plain `Hash`, exactly as the platform sent it. The SDK does not model the
@@ -578,7 +578,7 @@ deliberately.
 ```bash
 bundle install            # install dev dependencies
 bundle exec rake          # lint + tests (offline — the default)
-bundle exec rake test:live  # the spec drift-guard (one network call to the live spec)
+bundle exec rake test:live  # the drift-guard (one GET each of the live spec and API docs)
 bundle exec rubocop       # lint only
 gem build basecradle.gemspec  # build the gem
 actionlint                # lint the GitHub workflows (CI runs this; see below)

data/lib/basecradle/client.rb

@@ -40,8 +40,11 @@ module BaseCradle
     # idempotency key (see +max_retries+).
     DEFAULT_MAX_RETRIES = 0
 
-    # Backoff between retries doubles each attempt from this base (0.5s, 1s, 2s, …).
+    # Backoff between retries doubles each attempt from this base (0.5s, 1s, 2s, …), and
+    # is capped at RETRY_MAX_DELAY seconds, so a generous max_retries never sleeps for
+    # minutes between attempts.
     RETRY_BASE_DELAY = 0.5
+    RETRY_MAX_DELAY = 8.0
 
     # Connection failures Net::HTTP raises that mean "the request never got a response".
     CONNECTION_ERRORS = [
@@ -73,7 +76,8 @@ module BaseCradle
     # off. When set above 0, only requests that are safe to re-send are retried: any +GET+
     # (reads change nothing) and any create carrying an +idempotency_key+ (the platform
     # dedupes keyed creates, so a resend can't duplicate the record). An unkeyed +POST+ is
-    # never retried, whatever this is set to. Retries back off exponentially.
+    # never retried, whatever this is set to. Retries back off exponentially, capped at
+    # RETRY_MAX_DELAY seconds.
     def initialize(token = nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
                    max_retries: DEFAULT_MAX_RETRIES)
       resolved = token || ENV.fetch("BASECRADLE_TOKEN", nil)
@@ -347,9 +351,9 @@ module BaseCradle
       (200..299).cover?(response.code.to_i)
     end
 
-    # Exponential backoff before the next attempt (attempt is 1-based).
+    # Exponential backoff before the next attempt (attempt is 1-based), capped.
     def backoff(attempt)
-      sleep(RETRY_BASE_DELAY * (2**(attempt - 1)))
+      sleep([ RETRY_BASE_DELAY * 2**(attempt - 1), RETRY_MAX_DELAY ].min)
     end
 
     def build_uri(path, params)

data/lib/basecradle/contact_messages.rb

@@ -85,18 +85,23 @@ module BaseCradle
     end
 
     # Write a note about this contact message, and return it as a +Note+ (you are its
-    # author). Raises +ValidationError+ (422) for a blank body.
+    # author). A note can never be edited or deleted afterwards, by anyone. Raises
+    # +ValidationError+ (422) for a blank body, and appends nothing.
     #
-    # This object's own +notes+ is not touched: it is the record as fetched, and the API
-    # answers with the note alone. Fetch the contact message again
-    # (+bc.contact_messages.get(uuid)+) to read it with the new note embedded.
+    # The API answers with the note alone, in full, and this object appends it to its own
+    # +notes+ — unless a note with that +uuid+ is already there.
     #
     # Never auto-retried — the notes endpoint takes no +Idempotency-Key+, so a resend after
     # a lost response could write the note twice.
     def add_note(body:)
       response = require_client.request("POST", "/contact_messages/#{uuid}/notes",
                                         json: { "note" => { "body" => body } })
-      Note.new(response.fetch("note"), client: @client)
+      note = response.fetch("note")
+      notes = @data["notes"] || []
+      unless notes.any? { |existing| existing["uuid"] == note["uuid"] }
+        @data = @data.merge("notes" => notes + [ note ])
+      end
+      Note.new(note, client: @client)
     end
   end
 

data/lib/basecradle/dashboard.rb

@@ -15,6 +15,19 @@ module BaseCradle
     attribute :name
     attribute :summary
     attribute :you_are
+    attribute :concepts_url # the vocabulary: timeline, participation, trust, task, ...
+  end
+
+  # How lists page, and what is safe to checkpoint on — the gist plus the full guide.
+  class DashboardPagination < ApiObject
+    attribute :summary
+    attribute :guide_url
+  end
+
+  # Platform tools are thin wrappers over this same HTTP API — there is no other backend.
+  class DashboardTools < ApiObject
+    attribute :summary
+    attribute :mapping_url # the tool-action → endpoint table
   end
 
   # Your data surfaces — timelines first, then every cross-timeline list.
@@ -25,6 +38,8 @@ module BaseCradle
     attribute :tasks_url
     attribute :webhook_endpoints_url
     attribute :webhook_events_url
+    attribute :pagination, wrap: DashboardPagination
+    attribute :tools, wrap: DashboardTools
   end
 
   # Where to manage yourself: profile, sessions, password.

data/lib/basecradle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BaseCradle
-  VERSION = "0.13.0"
+  VERSION = "0.14.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.13.0
+  version: 0.14.0
 platform: ruby
 authors:
 - Drawk Kwast