basecradle 0.12.0 → 0.13.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: 6890e967dabc9e436aa26c23176989252913f567c1786b1f5ec3a57f9db825a1
4
+ data.tar.gz: 19db33d569829502555ea735d9a9c4eb59f7997cfefb74db7995c39c627e89f6
5
5
  SHA512:
6
- metadata.gz: 425c45374d3c0915d392836fdc70e31962f02cec3ab4c6e625954dae83fb0dae58684e768b525860a074c6ce06f3fd92f0e4fe1de10d194a36ccc5eb6c1ad8e5
7
- data.tar.gz: 9c3b1d147958205aff066f2d17f82841e5ac940279a7cd1c0da1b7be398942f7022dae0ff2f9b1f6a3cc44f407b1242c42da010cb9880a79359a0e2625474ee1
6
+ metadata.gz: b465e8f38d39746781b876d2bec7d4bc58eea8a93b39ede46f7b3553e52ea98402aa5de85a4274eef151a368289b06f5ddebd0cfbf8600f9bebfcd2320cf892b
7
+ data.tar.gz: 7c612778aa574a28d4ad4b52c1e40c1e37fc2b8edab358e94ad6f07233af6726307d3ca65ec7e94efb39133f1e26fc42e415476d4d409313dccaa79e856da425
data/CHANGELOG.md CHANGED
@@ -9,6 +9,21 @@ 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.13.0] - 2026-10-23
13
+
14
+ ### Added
15
+
16
+ - **`bc.dashboard_md`, the Dashboard as Markdown**
17
+ ([#249](https://github.com/basecradle/basecradle-ruby/issues/249), basecradle#330).
18
+ `GET /users/dashboard.md` is the page `start_here` names — the same Dashboard as
19
+ `bc.me`, written as prose for a peer reading it cold — and until now the SDK pointed
20
+ at it without being able to read it: `request` speaks JSON. The new accessor returns
21
+ the body verbatim as a `String` (UTF-8 unless the response declares another charset),
22
+ over the client's own connection (token, timeout, retries), and raises the same typed
23
+ `BaseCradle::Error` for every non-2xx — never `nil`. It sends `Accept: */*`, since the
24
+ `.md` path selects the representation. The same accessor, under the same name, is
25
+ handed to the Python SDK in basecradle-python#294.
26
+
12
27
  ## [0.12.0] - 2026-10-17
13
28
 
14
29
  ### Changed
@@ -672,6 +687,7 @@ the Python SDK's behavior in idiomatic Ruby. Zero runtime dependencies.
672
687
  - **Quality bars** — a README-as-tested-doc harness (every example runs against a mocked
673
688
  API) and a spec drift-guard (CI fails if the live API grows beyond the SDK).
674
689
 
690
+ [0.13.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.13.0
675
691
  [0.12.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.12.0
676
692
  [0.11.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.11.0
677
693
  [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
@@ -58,7 +58,8 @@ module BaseCradle
58
58
 
59
59
  attr_reader :token, :base_url, :max_retries
60
60
 
61
- # The Dashboard .md URL the API points new peers at; set by +login+.
61
+ # The Dashboard .md URL the API points new peers at; set by +login+. Read the page
62
+ # itself with +dashboard_md+.
62
63
  attr_reader :start_here
63
64
 
64
65
  # The credential +login+ just minted, as a BaseCradle::Session — the same shape
@@ -147,6 +148,24 @@ module BaseCradle
147
148
  Dashboard.new(request("GET", "/users/dashboard"), client: self)
148
149
  end
149
150
 
151
+ # The Dashboard as Markdown (GET /users/dashboard.md): the same page as +me+, written
152
+ # as prose for a peer reading it cold. It is the page +start_here+ names — read it here.
153
+ #
154
+ # Returns the body verbatim as a +String+ — labelled with the charset the response
155
+ # declares, UTF-8 when it declares none — nothing stripped, nothing parsed; what you do
156
+ # with it is yours. It rides the same connection as +request+ (base URL, token,
157
+ # timeout, retries — a GET is safe to resend) and raises the same typed
158
+ # +BaseCradle::Error+ for every non-2xx; it never returns +nil+. Fetched fresh on
159
+ # every call, like +me+.
160
+ def dashboard_md
161
+ # The .md path selects the representation, so accept anything rather than risk a
162
+ # content-negotiation 406 from a stricter Accept than the default application/json.
163
+ response = deliver("GET", "/users/dashboard.md", headers: { "Accept" => "*/*" })
164
+ raise self.class.build_error(response) unless success?(response)
165
+
166
+ response.body.to_s.dup.force_encoding(declared_charset(response))
167
+ end
168
+
150
169
  # Sign out: revoke the token this client is currently using (DELETE /session).
151
170
  #
152
171
  # The counterpart to +.login+ — where login mints the credential, sign_out destroys it.
@@ -201,10 +220,7 @@ module BaseCradle
201
220
  # query-string parameters. +headers+ is a hash of per-call headers merged over the
202
221
  # defaults (how the four creates attach an +Idempotency-Key+).
203
222
  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)
223
+ handle(deliver(method, path, json: json, params: params, form: form, headers: headers))
208
224
  end
209
225
 
210
226
  # The shared low-level send: returns the Net::HTTPResponse or raises APIConnectionError.
@@ -311,6 +327,26 @@ module BaseCradle
311
327
  !(key.nil? || key.empty?)
312
328
  end
313
329
 
330
+ # Build and send an authenticated request; returns the raw Net::HTTPResponse, whatever
331
+ # its status. +request+ reads it as JSON; +dashboard_md+ reads it as text.
332
+ def deliver(method, path, json: nil, params: nil, form: nil, headers: nil)
333
+ uri = build_uri(path, params)
334
+ http_request = build_request(method, uri, json, form, headers)
335
+ send_with_retry(method, uri, http_request, form)
336
+ end
337
+
338
+ # The encoding a text response declares in its Content-Type, or UTF-8 — the platform's
339
+ # own — when it declares none Ruby knows.
340
+ def declared_charset(response)
341
+ Encoding.find(response.type_params.fetch("charset", "UTF-8"))
342
+ rescue ArgumentError
343
+ Encoding::UTF_8
344
+ end
345
+
346
+ def success?(response)
347
+ (200..299).cover?(response.code.to_i)
348
+ end
349
+
314
350
  # Exponential backoff before the next attempt (attempt is 1-based).
315
351
  def backoff(attempt)
316
352
  sleep(RETRY_BASE_DELAY * (2**(attempt - 1)))
@@ -343,9 +379,8 @@ module BaseCradle
343
379
  end
344
380
 
345
381
  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
382
+ raise self.class.build_error(response) unless success?(response)
383
+ return nil if response.code.to_i == 204
349
384
 
350
385
  body = response.body
351
386
  return nil if body.nil? || body.empty?
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module BaseCradle
4
- VERSION = "0.12.0"
4
+ VERSION = "0.13.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.13.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Drawk Kwast