basecradle 0.10.2 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4e662740bb7ecbde3769c3430a269cbe32a0c507a4244626688af1ca13ce3ce4
-  data.tar.gz: 64820f7409159b2cfd1b063a53c96858302bfc939e4ff2df17b6ffcaf3b494e5
+  metadata.gz: 40d7b447c5bbeb18244e440069f09432d808525a96ef2aa1232ae560c3c41194
+  data.tar.gz: 12bcc5f74631bd1f48fa8fbe6ea0882283e03cddfcdf68336ed631e7a68e8325
 SHA512:
-  metadata.gz: 6c7a007a0c7eef4fe1bb8d4d19fc108c361fc5e5d4a618d5d61600a0cdd55fbb6b97ecc5ea5c07ed8ac6488840b7cc33133c59a6160feab2a04222da73683eeb
-  data.tar.gz: 7059369ae648787b45a97afe3b12ba721474629078031ac036461732cc7dfc9d13e764b916f48a7e72fa96b248bac4c53c1ee3ed686f2abc98d13ed1c54a6c28
+  metadata.gz: 235a1d21044f525ca69c2cffb0909ffc05e8dcd2e63da7d2d5db51f30b34a7eeecf73434a029fc80b08421c1e04dcc61d0461f92e657e27a6b140a19e5f378f0
+  data.tar.gz: aa1f71ee1a7efdde1ca609d0768e23efc4c9a2b0f63602e43411752f05ef470b5bfb9cbb0eb4c2c3df38b99b3ca89fedf7de302ff01af5eafd869cd82af8208c

data/CHANGELOG.md

@@ -9,6 +9,175 @@ 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.11.0] - 2026-10-10
+
+### Added
+
+- **Contact messages and notes, the platform's first admin-only surface**
+  ([#229](https://github.com/basecradle/basecradle-ruby/issues/229), mirroring
+  basecradle#663). All six new operations are covered:
+  - `bc.contact_messages`: newest first and auto-paginating, narrowed with
+    `.filter(status: "received" | "closed" | "spam")`, and `.get(uuid)` for one record.
+  - `contact_message.update_status(status)`: sets the triage verdict and updates the
+    object in place.
+  - `contact_message.add_note(body:)`: returns the new `BaseCradle::Note`.
+  - `bc.notes` (every note, newest first) and `bc.notes.get(uuid)`.
+
+  A `ContactMessage` is a flat record. It embeds its notes in full, its `user` is `nil`
+  for a visitor without an account, and `data` (the vendors' slots) is the platform's
+  plain `Hash`, so the vendors are not modeled. A `Note` has the same shape everywhere
+  it appears, and its `notable` names its subject's `type` and `uuid`.
+- **`BaseCradle::NotAnAdminError`** (a `ForbiddenError`) for the new `not_an_admin`
+  code. Every one of the six operations raises it for a caller who is not an admin.
+- **`bc.me.admin`**, the Dashboard's admin-only sixth section (`contact_messages_url`,
+  `notes_url`, `guide_url`). It is present only for an admin. Reading it as anyone else
+  raises `MissingFieldError`, like any other withheld field.
+- **`BaseCradle::RequestHeaders`**, the shared class behind a recorded request's
+  headers. `WebhookEventHeaders` now subclasses it. Its lookups and render are
+  unchanged; the one difference is the wording of the `KeyError` for a missing header,
+  which now says "request" where it said "delivery". A contact message's `headers` is the new `ContactMessageHeaders`, which follows
+  the same rules: case-insensitive lookup, and a render that shows header names but
+  never their values. A visitor's request headers can carry that visitor's own
+  credentials, just as a webhook sender's can.
+
+### Fixed
+
+- **`binary_payload` maps to `BaseCradle::BinaryPayloadError`.** The API documents
+  this webhook-ingest code (415, a body that is not UTF-8 text) beside
+  `payload_too_large`, but the SDK's registry never listed it. A 415 therefore surfaced
+  as a bare `BaseCradle::Error` instead of its own class.
+
+### Note
+
+- **0.10.4 was never published.** Its version and changelog entry merged, but it was
+  never tagged, so its changes reach RubyGems for the first time in this release.
+
+## [0.10.4] - 2026-09-30
+
+### Changed
+
+- **The names-only render rule is one module, and a reflective test now asks it of every
+  class** ([#212](https://github.com/basecradle/basecradle-ruby/issues/212)). Every
+  renderable object in this SDK prints its field *names* and never its field values —
+  that is what keeps a `bc_uat_` token, an inbound sender's `Authorization` header and an
+  endpoint's `ingest_url` out of logs, REPL transcripts and exception messages. Until now
+  the rule was three hand-rolled copies of the same three methods with nothing asking the
+  question of a fourth class, which is precisely how 0.10.2's leak arrived:
+  `WebhookEventHeaders` was added as a `Hash` descendant, `Hash` brought its own render,
+  every header value printed, and the suite stayed green. `BaseCradle::RendersNamesOnly`
+  now supplies `inspect`, `to_s` and `pretty_print` to `ApiObject`, `Client` and
+  `WebhookEventHeaders`, and `test/basecradle/rendering_test.rb` walks the SDK's own
+  constants to assert every renderable class gets all three from it. **No existing render
+  changed**, `Client`'s included — this is the same output from one place instead of
+  three, plus the guard. No leak was found; this closes the shape of the last one.
+- **A record interpolates as its field names instead of a heap address.** `ApiObject` had
+  no `to_s` or `pretty_print` of its own, so `"#{message}"` and `puts message` gave
+  `#<BaseCradle::Message:0x000074385e23d470>`. They now give
+  `#<BaseCradle::Message body, uuid>`, the same string `inspect` and `pp` already gave.
+  Nothing was leaking — a heap address is not a value — but two of the three doors on the
+  SDK's most common object belonged to `Kernel` rather than to the rule.
+### Fixed
+
+- **A record with mixed-type keys no longer raises from its own render.** `ApiObject`
+  sorted its field names with `sort`, which refuses `comparison of Symbol with String
+  failed` — reachable because the README documents rebuilding a model from a cached
+  record, and a cache layer that symbolizes some keys hands back exactly that. It was one
+  raising door before and would have been three after the change above, so it now sorts
+  by the names' string form, as `WebhookEventHeaders` always has.
+- **A record with no fields renders as `#<BaseCradle::Message>`**, not
+  `#<BaseCradle::Message >` with a dangling space. Reachable whenever the API sends a
+  nested content object as `{}`.
+
+- **The ActiveSupport harness renders the class 0.10.2 secured.** The child-process probe
+  excluded `Hash` descendants, which was a true statement about *serialization* (a
+  delivery's headers are a record and serialize) applied to a render question it does not
+  answer — so the one class that fix was written for was never rendered under real
+  ActiveSupport by the harness that exists for that. There is now a records bucket,
+  covered reflectively against every `Hash` descendant the SDK defines, asserting both
+  halves: the render stays names-only through all three doors, and the record still
+  serializes.
+
+## [0.10.3] - 2026-09-30
+
+### Security
+
+- **`Marshal.dump` and `to_yaml` no longer emit a `Client`'s token**
+  ([#205](https://github.com/basecradle/basecradle-ruby/issues/205)). 0.10.1 shut the
+  JSON door on a client; `Marshal` and Psych walk instance variables directly, consult no
+  `as_json`, and need no ActiveSupport to do it — so both still wrote the raw `bc_uat_`
+  credential into their output. They are the worse pair, because they are what puts a
+  token *at rest*: ActiveSupport's cache stores marshal what you write, so
+  `Rails.cache.write("bc", bc)` landed it in Redis, memcached or a file store; a
+  Marshal-backed session landed it in the session; Delayed::Job YAMLs its handler into
+  the database. (Queue backends that serialize arguments as **JSON** — ActiveJob and
+  Sidekiq among them — go through `to_json`, and so were already closed in 0.10.1.)
+  `Marshal.dump(bc)`, `bc.to_yaml`,
+  `YAML.dump(conn: bc)` and the `Marshal.load(Marshal.dump(bc))` deep-copy idiom now all
+  raise `BaseCradle::NotSerializableError`, the same typed error with the same message
+  the JSON door already raised. Long-standing and latent; no token is known to have been
+  emitted.
+- **The collection door was the wider one, not the narrower one.** Through JSON, a
+  collection never reached the token — ActiveSupport's `Enumerable#as_json` shadows
+  `Object#as_json`, so `bc.messages.to_json` serialized fetched records, never the client
+  held in an ivar. `Marshal` and Psych have no such shadow, so
+  **`Marshal.dump(bc.messages)` reached the credential where `bc.messages.to_json` never
+  did** — and a query is the likelier of the two to be handed to a cache. Every lazy
+  collection (`bc.timelines`, `bc.messages`, `timeline.tasks`, any `.filter(...)`, the
+  `Paginator` behind them) now refuses through all four doors; the refusals are on the
+  shared `NotSerializable` mixin, so a resource added later is covered by construction.
+  **`.to_a` is only half the remedy for a dumper** — the array it hands back is full of
+  models that each hold the client, so `Marshal.dump(bc.messages.to_a)` lands back on the
+  same error. Dump `bc.messages.to_a.map(&:to_h)`, which the refusal now says.
+- **Anything holding a client refuses too — models included, and that is the fix.** Both
+  walkers recurse, so `Marshal.dump(message)` and `message.to_yaml` reached the client's
+  token where `message.to_json` (which serializes the wire record) never did. They now
+  raise, naming `BaseCradle::Client` as what was reached. **If you cache or enqueue
+  models, cache the record instead** — `message.to_h` is the wire `Hash`, holds no
+  client, and marshals exactly as it always did; rebuild with
+  `BaseCradle::Message.new(record, client: bc)` when you need the verbs back. Nothing
+  else changed: `to_json`, `as_json`, `to_h`, `inspect`, every field reader and
+  `dup`/`clone` (which do not go through `Marshal`) are untouched. This matches the
+  Python SDK, whose `__reduce__` refusal says the same thing — *“Nothing holding a client
+  can be serialized either … copy the record's data instead.”*
+
+### Known limitation
+
+- **YAML reaches the `Enumerator` escape that 0.10.1 documented for JSON, on plain
+  Ruby.** Every refusal here is on this SDK's own objects; an `Enumerator` you build from
+  a collection (`bc.messages.each`, `bc.messages.lazy`) is a plain Ruby object this SDK
+  does not own and may not patch. Psych iterates one to dump it — with **no
+  ActiveSupport required**, where the `to_json` version is inert without it — so
+  `bc.messages.each.to_yaml` fires the page-by-page GET loop and *then* raises
+  `NotSerializableError` on the first record, which holds the client: the requests are
+  spent and no document comes out. `Marshal` is the exception — Ruby itself refuses to
+  dump an `Enumerator` at all. No token is exposed through any of them. Call `.first(n)`
+  or `.to_a` before a renderer, and `.map(&:to_h)` too before a dumper.
+- **Four doors is every hook Ruby gives a library**, not every way bytes can be made. A
+  serializer that reads instance variables directly rather than through `as_json`,
+  `to_json`, `marshal_dump` or `encode_with` is outside what this SDK can intercept.
+  Keep a client out of one.
+
+### Migrating
+
+Nothing to change unless you `Marshal.dump` or `to_yaml` something that holds a client.
+If you do:
+
+- **Caching or enqueuing a model** — `Rails.cache.write(key, message)`,
+  `Rails.cache.fetch(key) { bc.messages.get(id) }` — now raises
+  `BaseCradle::NotSerializableError` where it used to write your token to the store.
+  Cache `message.to_h`, the wire `Hash`, and rebuild with
+  `BaseCradle::Message.new(record, client: bc)` if you need the verbs back.
+- **Caching or enqueuing a client or a collection** — serialize nothing; build a client
+  where you need one (`BaseCradle::Client.new(token)`), moving the token only through
+  whatever you already trust with secrets. For a collection, `.to_a` / `.first(n)` is
+  enough for JSON but **not** for a dumper — use `bc.messages.to_a.map(&:to_h)`, since
+  the models in that array each hold the client.
+- **Deep-copying with `Marshal.load(Marshal.dump(x))`** — refuses at the dump for the
+  same objects. `dup` and `clone` do not go through `Marshal` and are unchanged.
+
+If any of these ran in production against a real store, treat the token as disclosed and
+rotate it: `bc.sessions` lists your credentials and `session.revoke` retires one.
+
 ## [0.10.2] - 2026-09-30
 
 ### Security
@@ -484,6 +653,9 @@ 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.11.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.11.0
+[0.10.4]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.4
+[0.10.3]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.3
 [0.10.2]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.2
 [0.10.1]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.1
 [0.10.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.0

data/README.md

@@ -337,6 +337,56 @@ timeline = bc.timelines.create(name: "Incident response")
 timeline.add_participant(nova)
 ```
 
+## Contact messages & notes (admin-only)
+
+**Admin-only.** Every call in this section raises `BaseCradle::NotAnAdminError` (a
+`ForbiddenError`, code `not_an_admin`) for anyone who is not a platform admin. The SDK
+sends the request either way, because the platform decides who is an admin. To check
+first, use `bc.me.identity.admin?`; an admin's Dashboard also carries a sixth section,
+`bc.me.admin`, with the URLs of both surfaces.
+
+A **contact message** is what someone sent through the public contact page. It is
+stored with the request's own details and with what the risk-assessment vendors said
+about it. A **note** is an admin's dated, signed remark about a record. Notes are never
+edited or deleted.
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new
+
+bc.contact_messages.filter(status: "received").each do |message|  # newest first
+  puts [message.name, message.email_address, message.body].inspect
+  puts message.user&.handle            # nil for a visitor without an account
+  puts message.honeypot_filled         # the bot trap: the platform records it, never acts on it
+  puts message.data.keys.inspect       # one self-describing slot per vendor
+
+  message.update_status("spam") if message.honeypot_filled  # "received" | "closed" | "spam"
+end
+
+message = bc.contact_messages.get("019e7750-66ee-7b28-b052-67cdb5b10ca0")
+note = message.add_note(body: "Looks genuine. Replied by email.")
+puts note.notable.type   # "contact_message": what the note is about
+message.notes.each { |n| puts [n.user.handle, n.body].inspect }  # notes come embedded
+
+bc.notes.each { |n| puts n.body }  # every note, across every subject, newest first
+```
+
+A contact message is a flat record with no `type`/`content` wrapper, so `message.uuid`
+is its identity. `update_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
+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
+vendors, which can change on the platform's side. Each slot names its `vendor`, the
+`api` it called, its `docs`, and then exactly one of `answer`, `skipped` or `error`. The
+scores do not all point the same way: Google's runs from 0.0 (bot) to 1.0 (human), and
+the IP vendors' run from 0 to 100, higher being worse. `headers` follows the same rules
+as a webhook delivery's: lookup ignores case, and a render shows header names but never
+their values.
+
 ## Reading models, and serializing them
 
 Every model is a read-only, wire-exact view of one API JSON object. Field readers mirror
@@ -375,10 +425,15 @@ something Rails renders comes out right too. Three caveats worth knowing:
 ## What does not serialize: clients and collections
 
 Two things in this SDK are *not* records, and serializing either raises
-`BaseCradle::NotSerializableError` rather than emitting something:
+`BaseCradle::NotSerializableError` rather than emitting something — and under `Marshal`
+and YAML, so does anything *holding* one, models included (see below). Four doors refuse:
+`to_json`, `as_json`, `Marshal.dump` and `to_yaml` — every hook Ruby gives a library to
+intercept. A serializer that reads instance variables directly instead of through those
+hooks is outside what any library can stop, so keep a client out of one.
 
 ```ruby
 require "basecradle"
+require "yaml"
 
 bc = BaseCradle::Client.new
 
@@ -394,6 +449,18 @@ rescue BaseCradle::NotSerializableError => e
   puts e.message.include?(".to_a")    # => true
 end
 
+begin
+  Marshal.dump(bc)                    # and Rails.cache.write("bc", bc), a job argument
+rescue BaseCradle::NotSerializableError => e
+  puts e.message.include?("bc_uat_")  # => true
+end
+
+begin
+  bc.messages.to_yaml                 # YAML walks the ivars, and reaches the client
+rescue BaseCradle::NotSerializableError => e
+  puts e.message.include?(".to_a")    # => true
+end
+
 puts bc.messages.first(20).to_json    # serialize the page you actually asked for
 ```
 
@@ -410,18 +477,89 @@ walk — but a client's instance variables are eight collections, so serializing
 ran those loops too, on its way to the credential.) Call `.to_a` or `.first(n)` yourself
 and serialize that, so how much you fetch is a visible act in your code.
 
-Both refusals happen before any HTTP — but they are on the SDK's own objects. An
+**`Marshal` and YAML are the same refusal for a different reason.** Both walk instance
+variables directly, so neither needed ActiveSupport to reach the token — and neither is
+shadowed the way `Enumerable#as_json` shadowed the ivar walk, so `Marshal.dump(bc.messages)`
+reached the credential where `bc.messages.to_json` never did. They are also where a leaked
+token stops being a log line and becomes a token *at rest*: ActiveSupport's cache stores
+marshal what you write, so `Rails.cache.write("bc", bc)` landed it in Redis, memcached or
+a file; a Marshal-backed session landed it in the session; Delayed::Job YAMLs its handler
+into the database. `Marshal.load(Marshal.dump(x))`, the deep-copy idiom, refuses at the
+dump. (Queue backends that serialize arguments as **JSON** — ActiveJob and Sidekiq among
+them — go through `to_json`, and so were already closed in 0.10.1.)
+
+**Anything *holding* a client refuses too, models included** — both walkers recurse, so
+`Marshal.dump(message)` reaches the client and raises naming `BaseCradle::Client`. That is
+the fix, not a limitation: before, it emitted the token. It is also why **`.to_a` is only
+half the remedy for a dumper**: the array it hands back is full of models that each hold
+the client, so `Marshal.dump(bc.messages.to_a)` lands straight back on the same error.
+Dump the wire records — which is what you wanted in a cache anyway:
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new
+message = bc.messages.first
+
+record = message.to_h                                  # the wire Hash, no client in it
+puts Marshal.load(Marshal.dump(record)) == record      # => true
+
+page = bc.messages.first(20).map(&:to_h)               # a whole page, no client in it
+puts Marshal.load(Marshal.dump(page)) == page          # => true
+```
+
+Rebuild a model from a cached record with `BaseCradle::Message.new(record, client: bc)`
+when you need its verbs back.
+
+Every refusal happens before any HTTP — but they are on the SDK's own objects. An
 `Enumerator` you built from one is a plain Ruby object this SDK does not own, so
 `render json: { recent: bc.messages.lazy }` and `bc.messages.each.to_json` still page the
-whole resource. Call `.first(n)` or `.to_a` before handing a query to a renderer.
+whole resource. **YAML reaches that escape on plain Ruby**, where the `to_json` version
+needs ActiveSupport: Psych iterates an `Enumerator` to dump it, so
+`bc.messages.each.to_yaml` fires the page-by-page GET loop and *then* raises
+`NotSerializableError` on the first record (which holds the client) — the requests are
+spent, and no document comes out. (`Marshal` is the exception: Ruby itself refuses to
+dump an `Enumerator` at all.) No token is exposed through any of them. Call `.first(n)`
+or `.to_a` before handing a query to a renderer, and `.map(&:to_h)` too before a dumper.
+
+### Renders show names, never values
+
+Every object in this SDK prints its **field names** and none of its field values, through
+all three doors a render arrives by — `inspect` (`p`, a REPL echo), `to_s` (string
+interpolation, `puts`) and `pretty_print` (`pp`). That is what keeps your `bc_uat_` token,
+an inbound sender's `Authorization` header and an endpoint's `ingest_url` out of logs,
+exception messages and transcripts:
+
+```ruby
+bc = BaseCradle::Client.new
 
-`bc.inspect` and `"#{bc}"` are redacted for the same reason — Ruby's default `inspect`
-dumps every instance variable, which would print the token into every exception message
-and REPL transcript that touched a client:
+bc.inspect   # => "#<BaseCradle::Client base_url=\"https://basecradle.com\" token=[REDACTED]>"
+"#{bc}"      # => "#<BaseCradle::Client base_url=\"https://basecradle.com\" token=[REDACTED]>"
 
+# A record, built here from a wire hash the way a cache round-trip hands one back.
+message = BaseCradle::Message.new(
+  { "uuid" => "019e7750-66ee-7c31-9a7f-2b6d5e8a9c04",
+    "actor" => { "handle" => "nova" },
+    "content" => { "body" => "the body text" } },
+  client: bc
+)
+
+message.inspect              # => "#<BaseCradle::Message actor, content, uuid>"
+"#{message}"                 # => "#<BaseCradle::Message actor, content, uuid>"
+message["content"]["body"]   # => "the body text" — reads are untouched
+
+headers = BaseCradle::WebhookEventHeaders.new(
+  { "Content-Type" => "application/json", "Authorization" => "Bearer the-senders-secret" }
+)
+
+headers.inspect          # => "#<BaseCradle::WebhookEventHeaders Authorization, Content-Type>"
+headers["authorization"] # => "Bearer the-senders-secret" — still readable, and case-folded
 ```
-#<BaseCradle::Client base_url="https://basecradle.com" token=[REDACTED]>
-```
+
+The values are always there to *read* — `message["body"]`, `message.to_h`,
+`event.content.headers["Authorization"]`, `to_json` — they are simply never what a render
+prints. If you want a record's contents in a log, log `message.to_h` and decide that
+deliberately.
 
 ## Development
 

data/lib/basecradle/api_object.rb

@@ -3,6 +3,7 @@
 require "json"
 
 require_relative "errors"
+require_relative "rendering"
 
 module BaseCradle
   # The uuid for a value that may be a model object or a uuid string. A model's identity
@@ -36,6 +37,10 @@ module BaseCradle
   # Objects built by a client carry a reference to it, so resource verbs added in later
   # releases (e.g. +timeline.lock+) can act on the platform.
   class ApiObject
+    # A record renders as its field names — never its values, which are whatever the API
+    # sent (a webhook endpoint's ingest_url among them).
+    include RendersNamesOnly
+
     def initialize(data, client: nil)
       @data = data
       @client = client
@@ -112,12 +117,27 @@ module BaseCradle
       [ self.class, @data ].hash
     end
 
-    def inspect
-      "#<#{self.class} #{@data.keys.sort.join(', ')}>"
-    end
-
     private
 
+    # The record's wire field names, sorted — never their values. A record holds whatever
+    # the API sent, which for a webhook endpoint includes its ingest_url.
+    #
+    # Sorted by their string form, not by `sort`: a record can be rebuilt from a cached
+    # hash (the README says so), and a caller whose cache layer symbolized some keys hands
+    # us mixed types, which `sort` refuses with `comparison of Symbol with String failed`.
+    # That used to raise from `inspect` alone and now would raise from interpolation and
+    # `pp` too — a render that blows up a log line is worse than the disorder it avoids.
+    # RequestHeaders#render_body (formerly WebhookEventHeaders') has always done this, for
+    # the same reason.
+    #
+    # nil, not "", for a record with no fields: the module renders nil as the bare class,
+    # and `"#<BaseCradle::Message >"` with its dangling space was never intended output.
+    def render_body
+      return nil if @data.empty?
+
+      @data.keys.sort_by(&:to_s).join(", ")
+    end
+
     # The client this object came from — required by verbs that call the API (later releases).
     def require_client
       return @client if @client

data/lib/basecradle/client.rb

@@ -4,9 +4,11 @@ require "json"
 require "net/http"
 require "uri"
 
+require_relative "contact_messages"
 require_relative "dashboard"
 require_relative "errors"
 require_relative "items"
+require_relative "rendering"
 require_relative "serialization"
 require_relative "sessions"
 require_relative "timelines"
@@ -25,8 +27,10 @@ module BaseCradle
   # endpoints added before the SDK wraps them (the API is additive-only).
   class Client
     # A client is a connection holding a live credential, never a record: serializing one
-    # raises rather than write the token into a response body or a log line.
+    # raises rather than write the token into a response body or a log line, and rendering
+    # one prints the marker below rather than the token.
     include NotSerializable
+    include RendersNamesOnly
 
     DEFAULT_BASE_URL = "https://basecradle.com"
     DEFAULT_TIMEOUT = 30
@@ -89,6 +93,8 @@ module BaseCradle
       @webhook_events = WebhookEventsResource.new(self)
       @sessions = SessionsResource.new(self)
       @users = UsersResource.new(self)
+      @contact_messages = ContactMessagesResource.new(self)
+      @notes = NotesResource.new(self)
     end
 
     # Your timelines — iterable (auto-paginating, newest first), with create/get.
@@ -103,6 +109,10 @@ module BaseCradle
     # The directory of other peers, and the trust handshake.
     attr_reader :users
 
+    # Admin-only: what the public contact page received, and the notes admins write about
+    # it. A non-admin's call raises NotAnAdminError (see ContactMessagesResource).
+    attr_reader :contact_messages, :notes
+
     # Mint a fresh token via POST /session and return an authenticated client.
     #
     # The minted token is on the returned client as +#token+ — save it; it is never
@@ -197,22 +207,6 @@ module BaseCradle
       handle(response)
     end
 
-    # Never the token. Ruby's default +inspect+ dumps every ivar, which would print the
-    # credential into every exception message, REPL transcript and +p+ call that touched
-    # a client — the same leak as serializing one, through a different door. The
-    # redaction marker is fixed text, so what it stands for cannot be guessed from its
-    # length. +to_s+ is the same string: string interpolation is the door people reach
-    # for without thinking about it.
-    def inspect
-      "#<#{self.class} base_url=#{@base_url.inspect} token=[REDACTED]>"
-    end
-
-    # Late-bound rather than `alias to_s inspect`, so a subclass that redacts more in
-    # inspect is not bypassed by interpolation.
-    def to_s
-      inspect
-    end
-
     # The shared low-level send: returns the Net::HTTPResponse or raises APIConnectionError.
     def self.perform(uri, request, timeout)
       http = Net::HTTP.new(uri.host, uri.port)
@@ -243,14 +237,38 @@ module BaseCradle
 
     private
 
-    # Why +to_json+ / +as_json+ refuse (see BaseCradle::NotSerializable). A client is not
-    # a record, and the thing it would emit is a live credential.
+    # Never the token. Ruby's default render dumps every ivar, which would print the
+    # credential into every exception message, REPL transcript, +pp+ and string
+    # interpolation that touched a client — the same leak as serializing one, through
+    # three different doors. The marker is fixed text, so what it stands for cannot be
+    # guessed from its length. The base URL is not a secret and is the one thing worth
+    # knowing about a client at a glance.
+    def render_body
+      "base_url=#{@base_url.inspect} token=[REDACTED]"
+    end
+
+    # Why every serializer refuses — +to_json+ / +as_json+, +Marshal.dump+, +to_yaml+
+    # (see BaseCradle::NotSerializable). A client is not a record, and the thing it would
+    # emit is a live credential.
+    #
+    # The last sentence is for the caller who never named a client: Marshal and Psych
+    # recurse, so dumping a model or a resource reaches the client it holds and lands
+    # here. Telling that caller only about clients would be telling them about an object
+    # they did not pass — the Python SDK's +__reduce__+ is worded for the same reason
+    # ("copying a resource or a record reaches this too — copy the record's data").
+    #
+    # And it has to name +to_h+, because the first remedy does not hold through those two
+    # doors: a model serializes as its record through JSON, but <tt>Marshal.dump(bc.me)</tt>
+    # walks to the client again. Advice that fails through the door the reader just used
+    # is worse than none.
     def serialization_refusal
       "#{self.class} is a connection holding your bc_uat_ token, not a record. " \
-      "Serializing it writes the raw credential into whatever you were rendering or " \
-      "logging, and a token in a log is a token to rotate. Serialize the record you " \
-      "meant instead (bc.me, a timeline, a message), or bc.base_url to name the " \
-      "connection itself."
+      "Serializing it writes the raw credential into whatever you were rendering, " \
+      "logging or storing, and a token in a log or a cache is a token to rotate. " \
+      "Serialize the record you meant instead (bc.me, a timeline, a message), or " \
+      "bc.base_url to name the connection itself. Marshal and YAML reach a client " \
+      "through anything holding one, models included, so dump the wire record rather " \
+      "than the object: model.to_h holds no client."
     end
 
     # Record what the mint response said about the credential just issued. Private: only