basecradle 0.12.0 → 0.14.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 38e4a8615dfc599f925f007f022e20323dbb39555dbcc3556a867ccc7d6026dd
4
- data.tar.gz: 8460d80cc0d400cf5c513ba77f92589a7150f7b10df083c6cb2c123fc60692d3
3
+ metadata.gz: e52bd37f68c6961351dde4657cb665f346548f20023d9372166333ff943529b0
4
+ data.tar.gz: f5725693ace3374348be8ef9771db763533d7526ff902ac7f029b3425e061137
5
5
  SHA512:
6
- metadata.gz: 425c45374d3c0915d392836fdc70e31962f02cec3ab4c6e625954dae83fb0dae58684e768b525860a074c6ce06f3fd92f0e4fe1de10d194a36ccc5eb6c1ad8e5
7
- data.tar.gz: 9c3b1d147958205aff066f2d17f82841e5ac940279a7cd1c0da1b7be398942f7022dae0ff2f9b1f6a3cc44f407b1242c42da010cb9880a79359a0e2625474ee1
6
+ metadata.gz: 0c2c1cb2a1b5d23214bb743a6be23f1756565696bb2cb807f7c1634fa0fc4c24a326ea862fcbac2d25ed78b8f41f3ee1c1017dea3ca025909345a78b81703058
7
+ data.tar.gz: 70618de428d28dfa790c95f278ddcd043062c0759efd30f1c277204f1704b031977560ada0c8e31ad35c5ac8957e9010c4be846696b2ab011b6fc4a1eae0c91c
data/CHANGELOG.md CHANGED
@@ -9,6 +9,64 @@ section**. The newest heading is always the version `lib/basecradle/version.rb`
9
9
  a release writes its entry and its version in the same PR — and `test/changelog_test.rb`
10
10
  fails CI if the two ever disagree.
11
11
 
12
+ ## [0.14.0] - 2026-10-23
13
+
14
+ A parity release. The first full SDK parity audit (basecradle#715) checked every issue
15
+ ever filed on either SDK against the other's shipped code. This release brings over what
16
+ the Python SDK had and this one did not, plus one behavior the founder ruled on.
17
+
18
+ ### Added
19
+
20
+ - **The Dashboard's orientation blocks are typed**
21
+ ([#254](https://github.com/basecradle/basecradle-ruby/pull/254), mirroring
22
+ basecradle-python#188). `bc.me.environment.concepts_url` links the platform's
23
+ vocabulary. `bc.me.interaction.pagination` (a `BaseCradle::DashboardPagination`:
24
+ `summary`, `guide_url`) says how lists page and what is safe to checkpoint on.
25
+ `bc.me.interaction.tools` (a `BaseCradle::DashboardTools`: `summary`, `mapping_url`)
26
+ says that platform tools are thin wrappers over this same HTTP API. Both blocks read as
27
+ attributes, like every other section. They were previously reachable only as bare
28
+ Hashes through `[]`.
29
+ - **The drift-guard checks error codes too**
30
+ ([#253](https://github.com/basecradle/basecradle-ruby/pull/253), mirroring
31
+ basecradle-python#265). Besides the spec's endpoints, `rake test:live` now reads the
32
+ API docs' Error Codes table and fails when the platform documents a code that has no
33
+ typed exception in `BaseCradle::CODE_TO_ERROR`. Without a typed exception, callers would
34
+ get a bare `BaseCradle::Error` for that code. The offline suite also pins its error
35
+ catalog to the registry, so a mapping removed, or added without a test, fails CI.
36
+
37
+ ### Changed
38
+
39
+ - **`contact_message.add_note` appends the new note to `notes`**
40
+ ([#257](https://github.com/basecradle/basecradle-ruby/pull/257); founder ruling,
41
+ basecradle#715). It still returns the `BaseCradle::Note`. It now also appends that note
42
+ to the record's own `notes`, unless a note with the same `uuid` is already there, so you
43
+ no longer need to re-fetch the record to read it. This matches the Python SDK. Code that
44
+ appended the returned note by hand should stop doing so, or it will hold the note twice.
45
+ - **Retry backoff is capped at 8 seconds**
46
+ ([#255](https://github.com/basecradle/basecradle-ruby/pull/255), mirroring
47
+ basecradle-python#107). With `max_retries:` set, the wait still doubles from 0.5s, but it
48
+ never exceeds `BaseCradle::Client::RETRY_MAX_DELAY` (8.0). Before this, the tenth retry
49
+ waited 256 seconds.
50
+ - **Event Delivery is described as "outbound delivery", never "push"**
51
+ ([#256](https://github.com/basecradle/basecradle-ruby/pull/256), mirroring
52
+ basecradle-python#181). This is a wording change in the README and in the 0.4.0 entry
53
+ below; no behavior changes.
54
+
55
+ ## [0.13.0] - 2026-10-23
56
+
57
+ ### Added
58
+
59
+ - **`bc.dashboard_md`, the Dashboard as Markdown**
60
+ ([#249](https://github.com/basecradle/basecradle-ruby/issues/249), basecradle#330).
61
+ `GET /users/dashboard.md` is the page `start_here` names — the same Dashboard as
62
+ `bc.me`, written as prose for a peer reading it cold — and until now the SDK pointed
63
+ at it without being able to read it: `request` speaks JSON. The new accessor returns
64
+ the body verbatim as a `String` (UTF-8 unless the response declares another charset),
65
+ over the client's own connection (token, timeout, retries), and raises the same typed
66
+ `BaseCradle::Error` for every non-2xx — never `nil`. It sends `Accept: */*`, since the
67
+ `.md` path selects the representation. The same accessor, under the same name, is
68
+ handed to the Python SDK in basecradle-python#294.
69
+
12
70
  ## [0.12.0] - 2026-10-17
13
71
 
14
72
  ### Changed
@@ -578,7 +636,7 @@ enrichments come with them — but three things that worked on a `Hash` no longe
578
636
  header. The platform stores **at most one record per key** (scoped per timeline + author;
579
637
  per timeline for authorless webhook endpoints), so a replayed keyed create returns the
580
638
  **original record** — no duplicate record, no second **Event Delivery** event, no task
581
- activation. (Event Delivery is the platform's *outbound* push through your integration;
639
+ activation. (Event Delivery is the platform's *outbound* delivery to your integration;
582
640
  the webhook endpoints named above are the *inbound* feature the SDK models — opposite
583
641
  directions, different features.) A key identifies one logical create: the same key with a
584
642
  different body still returns the original record. Keys never expire and never appear in a
@@ -672,6 +730,8 @@ the Python SDK's behavior in idiomatic Ruby. Zero runtime dependencies.
672
730
  - **Quality bars** — a README-as-tested-doc harness (every example runs against a mocked
673
731
  API) and a spec drift-guard (CI fails if the live API grows beyond the SDK).
674
732
 
733
+ [0.14.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.14.0
734
+ [0.13.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.13.0
675
735
  [0.12.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.12.0
676
736
  [0.11.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.11.0
677
737
  [0.10.4]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.4
data/README.md CHANGED
@@ -71,6 +71,18 @@ puts me.documentation.openapi # the API's machine contract, if you want i
71
71
 
72
72
  Every attribute mirrors the API's JSON exactly — what you read in the [API docs](https://basecradle.com/docs/api) is what you type here.
73
73
 
74
+ The same Dashboard also comes as Markdown prose, written for a peer reading it cold — the page `login` hands back as `bc.start_here`. `bc.dashboard_md` reads it:
75
+
76
+ ```ruby
77
+ require "basecradle"
78
+
79
+ bc = BaseCradle::Client.new
80
+ primer = bc.dashboard_md # GET /users/dashboard.md — the body verbatim, as a String
81
+ puts primer
82
+ ```
83
+
84
+ It is fetched fresh on every call, returned exactly as served (nothing stripped, nothing parsed), and a failure raises the same typed `BaseCradle::Error` as every other call — never `nil`.
85
+
74
86
  Your own identity also carries three read-only fields — `integration_url`, `integration_enabled`, and `integration_failure_count`. They report the status of your **integration**: the outbound connection the platform sends **Event Delivery** through. Like the rest of the self/admin cluster they are present on `bc.me.identity` (or an admin's view) and withheld elsewhere, where reading one raises `BaseCradle::MissingFieldError`. Configuring an integration is not an SDK surface — the SDK reports its status; it never sets the URL or flips the switch.
75
87
 
76
88
  ## Timelines
@@ -163,7 +175,7 @@ inventing a value.
163
175
 
164
176
  ## Webhooks
165
177
 
166
- 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.
178
+ 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.
167
179
 
168
180
  ```ruby
169
181
  require "basecradle"
@@ -246,7 +258,7 @@ A create can succeed on the server while its response is lost on the wire — re
246
258
 
247
259
  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.
248
260
 
249
- 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.
261
+ 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.
250
262
 
251
263
  ```ruby
252
264
  require "basecradle"
@@ -375,8 +387,8 @@ bc.notes.each { |n| puts n.body } # every note, across every subject, newest fi
375
387
  A contact message is a flat record with no `type`/`content` wrapper, so `message.uuid`
376
388
  is its identity. `set_status` changes the triage verdict in any direction (reopen with
377
389
  `"received"`). It updates the object you called it on and returns it. `add_note` returns
378
- the new `BaseCradle::Note` and leaves `message.notes` as it was fetched, so call
379
- `bc.contact_messages.get` again to read the record with the new note embedded. A note
390
+ the new `BaseCradle::Note` and appends it to `message.notes`, unless a note with that
391
+ `uuid` is already there. A note can never be edited or deleted afterwards. A note
380
392
  body is not idempotent, so `add_note` is never retried automatically.
381
393
 
382
394
  `data` is a plain `Hash`, exactly as the platform sent it. The SDK does not model the
@@ -566,7 +578,7 @@ deliberately.
566
578
  ```bash
567
579
  bundle install # install dev dependencies
568
580
  bundle exec rake # lint + tests (offline — the default)
569
- bundle exec rake test:live # the spec drift-guard (one network call to the live spec)
581
+ bundle exec rake test:live # the drift-guard (one GET each of the live spec and API docs)
570
582
  bundle exec rubocop # lint only
571
583
  gem build basecradle.gemspec # build the gem
572
584
  actionlint # lint the GitHub workflows (CI runs this; see below)
@@ -40,8 +40,11 @@ module BaseCradle
40
40
  # idempotency key (see +max_retries+).
41
41
  DEFAULT_MAX_RETRIES = 0
42
42
 
43
- # Backoff between retries doubles each attempt from this base (0.5s, 1s, 2s, …).
43
+ # Backoff between retries doubles each attempt from this base (0.5s, 1s, 2s, …), and
44
+ # is capped at RETRY_MAX_DELAY seconds, so a generous max_retries never sleeps for
45
+ # minutes between attempts.
44
46
  RETRY_BASE_DELAY = 0.5
47
+ RETRY_MAX_DELAY = 8.0
45
48
 
46
49
  # Connection failures Net::HTTP raises that mean "the request never got a response".
47
50
  CONNECTION_ERRORS = [
@@ -58,7 +61,8 @@ module BaseCradle
58
61
 
59
62
  attr_reader :token, :base_url, :max_retries
60
63
 
61
- # The Dashboard .md URL the API points new peers at; set by +login+.
64
+ # The Dashboard .md URL the API points new peers at; set by +login+. Read the page
65
+ # itself with +dashboard_md+.
62
66
  attr_reader :start_here
63
67
 
64
68
  # The credential +login+ just minted, as a BaseCradle::Session — the same shape
@@ -72,7 +76,8 @@ module BaseCradle
72
76
  # off. When set above 0, only requests that are safe to re-send are retried: any +GET+
73
77
  # (reads change nothing) and any create carrying an +idempotency_key+ (the platform
74
78
  # dedupes keyed creates, so a resend can't duplicate the record). An unkeyed +POST+ is
75
- # never retried, whatever this is set to. Retries back off exponentially.
79
+ # never retried, whatever this is set to. Retries back off exponentially, capped at
80
+ # RETRY_MAX_DELAY seconds.
76
81
  def initialize(token = nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
77
82
  max_retries: DEFAULT_MAX_RETRIES)
78
83
  resolved = token || ENV.fetch("BASECRADLE_TOKEN", nil)
@@ -147,6 +152,24 @@ module BaseCradle
147
152
  Dashboard.new(request("GET", "/users/dashboard"), client: self)
148
153
  end
149
154
 
155
+ # The Dashboard as Markdown (GET /users/dashboard.md): the same page as +me+, written
156
+ # as prose for a peer reading it cold. It is the page +start_here+ names — read it here.
157
+ #
158
+ # Returns the body verbatim as a +String+ — labelled with the charset the response
159
+ # declares, UTF-8 when it declares none — nothing stripped, nothing parsed; what you do
160
+ # with it is yours. It rides the same connection as +request+ (base URL, token,
161
+ # timeout, retries — a GET is safe to resend) and raises the same typed
162
+ # +BaseCradle::Error+ for every non-2xx; it never returns +nil+. Fetched fresh on
163
+ # every call, like +me+.
164
+ def dashboard_md
165
+ # The .md path selects the representation, so accept anything rather than risk a
166
+ # content-negotiation 406 from a stricter Accept than the default application/json.
167
+ response = deliver("GET", "/users/dashboard.md", headers: { "Accept" => "*/*" })
168
+ raise self.class.build_error(response) unless success?(response)
169
+
170
+ response.body.to_s.dup.force_encoding(declared_charset(response))
171
+ end
172
+
150
173
  # Sign out: revoke the token this client is currently using (DELETE /session).
151
174
  #
152
175
  # The counterpart to +.login+ — where login mints the credential, sign_out destroys it.
@@ -201,10 +224,7 @@ module BaseCradle
201
224
  # query-string parameters. +headers+ is a hash of per-call headers merged over the
202
225
  # defaults (how the four creates attach an +Idempotency-Key+).
203
226
  def request(method, path, json: nil, params: nil, form: nil, headers: nil)
204
- uri = build_uri(path, params)
205
- http_request = build_request(method, uri, json, form, headers)
206
- response = send_with_retry(method, uri, http_request, form)
207
- handle(response)
227
+ handle(deliver(method, path, json: json, params: params, form: form, headers: headers))
208
228
  end
209
229
 
210
230
  # The shared low-level send: returns the Net::HTTPResponse or raises APIConnectionError.
@@ -311,9 +331,29 @@ module BaseCradle
311
331
  !(key.nil? || key.empty?)
312
332
  end
313
333
 
314
- # Exponential backoff before the next attempt (attempt is 1-based).
334
+ # Build and send an authenticated request; returns the raw Net::HTTPResponse, whatever
335
+ # its status. +request+ reads it as JSON; +dashboard_md+ reads it as text.
336
+ def deliver(method, path, json: nil, params: nil, form: nil, headers: nil)
337
+ uri = build_uri(path, params)
338
+ http_request = build_request(method, uri, json, form, headers)
339
+ send_with_retry(method, uri, http_request, form)
340
+ end
341
+
342
+ # The encoding a text response declares in its Content-Type, or UTF-8 — the platform's
343
+ # own — when it declares none Ruby knows.
344
+ def declared_charset(response)
345
+ Encoding.find(response.type_params.fetch("charset", "UTF-8"))
346
+ rescue ArgumentError
347
+ Encoding::UTF_8
348
+ end
349
+
350
+ def success?(response)
351
+ (200..299).cover?(response.code.to_i)
352
+ end
353
+
354
+ # Exponential backoff before the next attempt (attempt is 1-based), capped.
315
355
  def backoff(attempt)
316
- sleep(RETRY_BASE_DELAY * (2**(attempt - 1)))
356
+ sleep([ RETRY_BASE_DELAY * 2**(attempt - 1), RETRY_MAX_DELAY ].min)
317
357
  end
318
358
 
319
359
  def build_uri(path, params)
@@ -343,9 +383,8 @@ module BaseCradle
343
383
  end
344
384
 
345
385
  def handle(response)
346
- status = response.code.to_i
347
- raise self.class.build_error(response) unless (200..299).cover?(status)
348
- return nil if status == 204
386
+ raise self.class.build_error(response) unless success?(response)
387
+ return nil if response.code.to_i == 204
349
388
 
350
389
  body = response.body
351
390
  return nil if body.nil? || body.empty?
@@ -85,18 +85,23 @@ module BaseCradle
85
85
  end
86
86
 
87
87
  # Write a note about this contact message, and return it as a +Note+ (you are its
88
- # author). Raises +ValidationError+ (422) for a blank body.
88
+ # author). A note can never be edited or deleted afterwards, by anyone. Raises
89
+ # +ValidationError+ (422) for a blank body, and appends nothing.
89
90
  #
90
- # This object's own +notes+ is not touched: it is the record as fetched, and the API
91
- # answers with the note alone. Fetch the contact message again
92
- # (+bc.contact_messages.get(uuid)+) to read it with the new note embedded.
91
+ # The API answers with the note alone, in full, and this object appends it to its own
92
+ # +notes+ — unless a note with that +uuid+ is already there.
93
93
  #
94
94
  # Never auto-retried — the notes endpoint takes no +Idempotency-Key+, so a resend after
95
95
  # a lost response could write the note twice.
96
96
  def add_note(body:)
97
97
  response = require_client.request("POST", "/contact_messages/#{uuid}/notes",
98
98
  json: { "note" => { "body" => body } })
99
- Note.new(response.fetch("note"), client: @client)
99
+ note = response.fetch("note")
100
+ notes = @data["notes"] || []
101
+ unless notes.any? { |existing| existing["uuid"] == note["uuid"] }
102
+ @data = @data.merge("notes" => notes + [ note ])
103
+ end
104
+ Note.new(note, client: @client)
100
105
  end
101
106
  end
102
107
 
@@ -15,6 +15,19 @@ module BaseCradle
15
15
  attribute :name
16
16
  attribute :summary
17
17
  attribute :you_are
18
+ attribute :concepts_url # the vocabulary: timeline, participation, trust, task, ...
19
+ end
20
+
21
+ # How lists page, and what is safe to checkpoint on — the gist plus the full guide.
22
+ class DashboardPagination < ApiObject
23
+ attribute :summary
24
+ attribute :guide_url
25
+ end
26
+
27
+ # Platform tools are thin wrappers over this same HTTP API — there is no other backend.
28
+ class DashboardTools < ApiObject
29
+ attribute :summary
30
+ attribute :mapping_url # the tool-action → endpoint table
18
31
  end
19
32
 
20
33
  # Your data surfaces — timelines first, then every cross-timeline list.
@@ -25,6 +38,8 @@ module BaseCradle
25
38
  attribute :tasks_url
26
39
  attribute :webhook_endpoints_url
27
40
  attribute :webhook_events_url
41
+ attribute :pagination, wrap: DashboardPagination
42
+ attribute :tools, wrap: DashboardTools
28
43
  end
29
44
 
30
45
  # Where to manage yourself: profile, sessions, password.
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module BaseCradle
4
- VERSION = "0.12.0"
4
+ VERSION = "0.14.0"
5
5
  end
metadata CHANGED
@@ -1,7 +1,7 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: basecradle
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.12.0
4
+ version: 0.14.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Drawk Kwast