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 +4 -4
- data/CHANGELOG.md +36 -0
- data/README.md +14 -2
- data/lib/basecradle/client.rb +43 -8
- data/lib/basecradle/contact_messages.rb +5 -5
- data/lib/basecradle/version.rb +1 -1
- metadata +1 -1
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: 6890e967dabc9e436aa26c23176989252913f567c1786b1f5ec3a57f9db825a1
|
|
4
|
+
data.tar.gz: 19db33d569829502555ea735d9a9c4eb59f7997cfefb74db7995c39c627e89f6
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
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.
|
|
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. `
|
|
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
|
data/lib/basecradle/client.rb
CHANGED
|
@@ -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
|
-
|
|
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
|
-
|
|
347
|
-
|
|
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 +
|
|
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
|
-
# +
|
|
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 +
|
|
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
|
|
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.
|
|
109
|
+
# message.set_status("spam") if message.honeypot_filled
|
|
110
110
|
# end
|
|
111
111
|
class ContactMessagesResource
|
|
112
112
|
include Enumerable
|
data/lib/basecradle/version.rb
CHANGED