basecradle 0.11.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: 40d7b447c5bbeb18244e440069f09432d808525a96ef2aa1232ae560c3c41194
4
- data.tar.gz: 12bcc5f74631bd1f48fa8fbe6ea0882283e03cddfcdf68336ed631e7a68e8325
3
+ metadata.gz: 6890e967dabc9e436aa26c23176989252913f567c1786b1f5ec3a57f9db825a1
4
+ data.tar.gz: 19db33d569829502555ea735d9a9c4eb59f7997cfefb74db7995c39c627e89f6
5
5
  SHA512:
6
- metadata.gz: 235a1d21044f525ca69c2cffb0909ffc05e8dcd2e63da7d2d5db51f30b34a7eeecf73434a029fc80b08421c1e04dcc61d0461f92e657e27a6b140a19e5f378f0
7
- data.tar.gz: aa1f71ee1a7efdde1ca609d0768e23efc4c9a2b0f63602e43411752f05ef470b5bfb9cbb0eb4c2c3df38b99b3ca89fedf7de302ff01af5eafd869cd82af8208c
6
+ metadata.gz: b465e8f38d39746781b876d2bec7d4bc58eea8a93b39ede46f7b3553e52ea98402aa5de85a4274eef151a368289b06f5ddebd0cfbf8600f9bebfcd2320cf892b
7
+ data.tar.gz: 7c612778aa574a28d4ad4b52c1e40c1e37fc2b8edab358e94ad6f07233af6726307d3ca65ec7e94efb39133f1e26fc42e415476d4d409313dccaa79e856da425
data/CHANGELOG.md CHANGED
@@ -9,6 +9,40 @@ 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
+
27
+ ## [0.12.0] - 2026-10-17
28
+
29
+ ### Changed
30
+
31
+ - **Breaking: `contact_message.update_status(status)` is now `contact_message.set_status(status)`**
32
+ ([#234](https://github.com/basecradle/basecradle-ruby/issues/234)). Same operation
33
+ (`PATCH /contact_messages/{id}/status`), same argument, same in-place update and
34
+ `self` return; only the name changes. An operation's verb is part of the SDK
35
+ contract: one operation, one verb in every SDK, taken from the API documentation's
36
+ name for it ("Setting a Contact Message's Status"). The Python SDK already says
37
+ `set_status`; this release brings Ruby to the same word (`@origin`, 2026-10-16;
38
+ basecradle#691). No alias is kept — the gem is 0.x and the method shipped one
39
+ release ago.
40
+
41
+ ### Migrating
42
+
43
+ Rename the call: `message.update_status("spam")` becomes `message.set_status("spam")`.
44
+ Calling the old name raises `NoMethodError`.
45
+
12
46
  ## [0.11.0] - 2026-10-10
13
47
 
14
48
  ### Added
@@ -653,6 +687,8 @@ the Python SDK's behavior in idiomatic Ruby. Zero runtime dependencies.
653
687
  - **Quality bars** — a README-as-tested-doc harness (every example runs against a mocked
654
688
  API) and a spec drift-guard (CI fails if the live API grows beyond the SDK).
655
689
 
690
+ [0.13.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.13.0
691
+ [0.12.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.12.0
656
692
  [0.11.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.11.0
657
693
  [0.10.4]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.4
658
694
  [0.10.3]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.3
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
@@ -361,7 +373,7 @@ bc.contact_messages.filter(status: "received").each do |message| # newest first
361
373
  puts message.honeypot_filled # the bot trap: the platform records it, never acts on it
362
374
  puts message.data.keys.inspect # one self-describing slot per vendor
363
375
 
364
- message.update_status("spam") if message.honeypot_filled # "received" | "closed" | "spam"
376
+ message.set_status("spam") if message.honeypot_filled # "received" | "closed" | "spam"
365
377
  end
366
378
 
367
379
  message = bc.contact_messages.get("019e7750-66ee-7b28-b052-67cdb5b10ca0")
@@ -373,7 +385,7 @@ bc.notes.each { |n| puts n.body } # every note, across every subject, newest fi
373
385
  ```
374
386
 
375
387
  A contact message is a flat record with no `type`/`content` wrapper, so `message.uuid`
376
- is its identity. `update_status` changes the triage verdict in any direction (reopen with
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
390
  the new `BaseCradle::Note` and leaves `message.notes` as it was fetched, so call
379
391
  `bc.contact_messages.get` again to read the record with the new note embedded. A note
@@ -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?
@@ -44,14 +44,14 @@ module BaseCradle
44
44
  # identity, and it embeds its notes in full.
45
45
  #
46
46
  # Nothing is ever rejected on a score — the record is the data, and an admin decides,
47
- # with +update_status+ and +add_note+.
47
+ # with +set_status+ and +add_note+.
48
48
  class ContactMessage < ApiObject
49
49
  attribute :uuid
50
50
  attribute :name
51
51
  attribute :email_address
52
52
  attribute :body
53
53
  # "received" (the default) | "closed" | "spam" — the triage verdict, set with
54
- # +update_status+. Treat an unrecognized value as forward-compatible, never an error.
54
+ # +set_status+. Treat an unrecognized value as forward-compatible, never an error.
55
55
  attribute :status
56
56
  # The signed-in user who submitted it (nested-actor form), or +nil+ for a visitor
57
57
  # without an account.
@@ -72,12 +72,12 @@ module BaseCradle
72
72
  attribute :updated_at
73
73
 
74
74
  # Set the triage verdict: +"received"+, +"closed"+ or +"spam"+. It moves in any
75
- # direction — reopening a closed message is +update_status("received")+.
75
+ # direction — reopening a closed message is +set_status("received")+.
76
76
  #
77
77
  # Live object: the API returns the whole contact message, and this object reads it from
78
78
  # here on (+status+ and +updated_at+ included), then returns +self+. Raises
79
79
  # +ValidationError+ (422) for a status outside the three.
80
- def update_status(status)
80
+ def set_status(status)
81
81
  response = require_client.request("PATCH", "/contact_messages/#{uuid}/status",
82
82
  json: { "contact_message" => { "status" => status } })
83
83
  @data = response.fetch("contact_message")
@@ -106,7 +106,7 @@ module BaseCradle
106
106
  # or fetch one by uuid. Admin-only.
107
107
  #
108
108
  # bc.contact_messages.filter(status: "received").each do |message|
109
- # message.update_status("spam") if message.honeypot_filled
109
+ # message.set_status("spam") if message.honeypot_filled
110
110
  # end
111
111
  class ContactMessagesResource
112
112
  include Enumerable
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module BaseCradle
4
- VERSION = "0.11.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.11.0
4
+ version: 0.13.0
5
5
  platform: ruby
6
6
  authors:
7
7
  - Drawk Kwast