basecradle 0.10.3 → 0.11.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b1fc584abdde2edfd9233ea937bf054ba6fb672708b6c815014d46a1dc4d59c2
-  data.tar.gz: bc53a3e49ad9eb40fd21e5fb2fe424d054738359a30eb2c137a26c8a5f634d27
+  metadata.gz: 40d7b447c5bbeb18244e440069f09432d808525a96ef2aa1232ae560c3c41194
+  data.tar.gz: 12bcc5f74631bd1f48fa8fbe6ea0882283e03cddfcdf68336ed631e7a68e8325
 SHA512:
-  metadata.gz: c603f01c320e465db82dc376ad78cfca4d52c63db107580be7366d2a2c3b79f99e1d5b3f356917bd1526b9f63bb294747cc218a1e7cf71e8fc22caa41ccc4b34
-  data.tar.gz: 401d5b9b58f5dc726fb3bc457180954b582e077b8b0aa224c0f92513a39c4122bac16ea56dfff4746e44e2b252cc88ab8a6cf12b178d989ee1eed5b2caf1d02a
+  metadata.gz: 235a1d21044f525ca69c2cffb0909ffc05e8dcd2e63da7d2d5db51f30b34a7eeecf73434a029fc80b08421c1e04dcc61d0461f92e657e27a6b140a19e5f378f0
+  data.tar.gz: aa1f71ee1a7efdde1ca609d0768e23efc4c9a2b0f63602e43411752f05ef470b5bfb9cbb0eb4c2c3df38b99b3ca89fedf7de302ff01af5eafd869cd82af8208c

data/CHANGELOG.md

@@ -9,6 +9,94 @@ 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
@@ -565,6 +653,8 @@ 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

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
@@ -472,13 +522,44 @@ spent, and no document comes out. (`Marshal` is the exception: Ruby itself refus
 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.
 
-`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:
+### 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   # => "#<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,6 +237,16 @@ module BaseCradle
 
     private
 
+    # 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.

data/lib/basecradle/contact_messages.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+require_relative "headers"
+require_relative "pagination"
+require_relative "serialization"
+require_relative "user"
+
+module BaseCradle
+  # Contact messages and notes are the platform's first **admin-only** surface. Every call
+  # in this file answers a non-admin with +NotAnAdminError+ (403, +not_an_admin+) — the
+  # SDK sends the request regardless, because the platform, not this library, decides who
+  # is an admin. +bc.me.admin+ is present only for an admin, if you want to ask first.
+
+  # --- models ---------------------------------------------------------------------------
+
+  # What a note is about: its subject's record type and uuid. Typed, because a note can be
+  # about any kind of record — today it is always a +"contact_message"+.
+  class Notable < ApiObject
+    attribute :type
+    attribute :uuid
+  end
+
+  # An admin's dated, signed remark about a record. A note **never changes**: there is no
+  # update and no delete, for anyone. One shape everywhere a note appears — fetched alone,
+  # listed, or embedded on its subject (+contact_message.notes+).
+  class Note < ApiObject
+    attribute :uuid
+    attribute :body
+    attribute :user, wrap: User # the author, nested-actor form
+    attribute :notable, wrap: Notable
+    attribute :created_at
+    attribute :updated_at
+  end
+
+  # A contact-page submission's request headers, exactly as the visitor's browser sent
+  # them — read through RequestHeaders' rules: case-insensitive lookup, and a render of
+  # names and never values, because a visitor's request can carry its own credentials.
+  class ContactMessageHeaders < RequestHeaders; end
+
+  # What someone sent through the public contact page, stored with everything the request
+  # told the platform and, after the fact, what the risk-assessment vendors said about it.
+  # A top-level record, so flat (no +type+ / +content+): +contact_message.uuid+ is its
+  # identity, and it embeds its notes in full.
+  #
+  # Nothing is ever rejected on a score — the record is the data, and an admin decides,
+  # with +update_status+ and +add_note+.
+  class ContactMessage < ApiObject
+    attribute :uuid
+    attribute :name
+    attribute :email_address
+    attribute :body
+    # "received" (the default) | "closed" | "spam" — the triage verdict, set with
+    # +update_status+. Treat an unrecognized value as forward-compatible, never an error.
+    attribute :status
+    # The signed-in user who submitted it (nested-actor form), or +nil+ for a visitor
+    # without an account.
+    attribute :user, wrap: User
+    attribute :ip_address
+    attribute :user_agent
+    attribute :headers, wrap: ContactMessageHeaders
+    attribute :honeypot_filled
+    attribute :fill_seconds # how long the form took to fill, or nil
+    # One self-describing slot per vendor (+vendor+, +api+, +docs+, +fetched_at+,
+    # +attempts+, then exactly one of +answer+ / +skipped+ / +error+). A plain Hash, read
+    # as the platform sent it — the vendors are the platform's to add and change, so the
+    # SDK models none of them. Note the scores do not all run the same way: see
+    # https://basecradle.com/docs/api.md#contact-messages.
+    attribute :data
+    attribute :notes, wrap: Note
+    attribute :created_at
+    attribute :updated_at
+
+    # Set the triage verdict: +"received"+, +"closed"+ or +"spam"+. It moves in any
+    # direction — reopening a closed message is +update_status("received")+.
+    #
+    # Live object: the API returns the whole contact message, and this object reads it from
+    # here on (+status+ and +updated_at+ included), then returns +self+. Raises
+    # +ValidationError+ (422) for a status outside the three.
+    def update_status(status)
+      response = require_client.request("PATCH", "/contact_messages/#{uuid}/status",
+                                        json: { "contact_message" => { "status" => status } })
+      @data = response.fetch("contact_message")
+      self
+    end
+
+    # Write a note about this contact message, and return it as a +Note+ (you are its
+    # author). Raises +ValidationError+ (422) for a blank body.
+    #
+    # This object's own +notes+ is not touched: it is the record as fetched, and the API
+    # answers with the note alone. Fetch the contact message again
+    # (+bc.contact_messages.get(uuid)+) to read it with the new note embedded.
+    #
+    # Never auto-retried — the notes endpoint takes no +Idempotency-Key+, so a resend after
+    # a lost response could write the note twice.
+    def add_note(body:)
+      response = require_client.request("POST", "/contact_messages/#{uuid}/notes",
+                                        json: { "note" => { "body" => body } })
+      Note.new(response.fetch("note"), client: @client)
+    end
+  end
+
+  # --- collections ----------------------------------------------------------------------
+
+  # Every contact message, newest first, auto-paginating — narrow with +.filter(status:)+,
+  # or fetch one by uuid. Admin-only.
+  #
+  #   bc.contact_messages.filter(status: "received").each do |message|
+  #     message.update_status("spam") if message.honeypot_filled
+  #   end
+  class ContactMessagesResource
+    include Enumerable
+    include NotSerializableCollection
+
+    def initialize(client, filters: {})
+      @client = client
+      @filters = filters
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/contact_messages", envelope_key: "contact_messages",
+                                                  model: ContactMessage, params: @filters).each(&block)
+    end
+
+    # A new lazy resource narrowed by status: +"received"+, +"closed"+ or +"spam"+. Any
+    # other value is the API's to refuse (+InvalidFilterError+, 400).
+    def filter(status: nil)
+      filters = @filters.dup
+      filters["status"] = status unless status.nil?
+      self.class.new(@client, filters: filters)
+    end
+
+    # Fetch one contact message by its uuid.
+    def get(uuid)
+      ContactMessage.new(@client.request("GET", "/contact_messages/#{uuid}").fetch("contact_message"),
+                         client: @client)
+    end
+  end
+
+  # Every note, across every subject, newest first, auto-paginating — or fetch one by uuid.
+  # Admin-only. Notes are written from their subject (+contact_message.add_note+), never
+  # from here.
+  class NotesResource
+    include Enumerable
+    include NotSerializableCollection
+
+    def initialize(client)
+      @client = client
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/notes", envelope_key: "notes", model: Note).each(&block)
+    end
+
+    # Fetch one note by its uuid.
+    def get(uuid)
+      Note.new(@client.request("GET", "/notes/#{uuid}").fetch("note"), client: @client)
+    end
+  end
+end

data/lib/basecradle/dashboard.rb

@@ -34,6 +34,13 @@ module BaseCradle
     attribute :change_password_url
   end
 
+  # The operator's surfaces — present on the Dashboard only for an admin.
+  class DashboardAdmin < ApiObject
+    attribute :contact_messages_url
+    attribute :notes_url
+    attribute :guide_url
+  end
+
   # One official SDK: where its code lives and where to install it from.
   class DashboardSdk < ApiObject
     attribute :repository
@@ -58,12 +65,17 @@ module BaseCradle
   end
 
   # Who am I, what is this place, where is everything — the answer every freshly-woken
-  # peer asks first. Identity · environment · interaction · account · documentation.
+  # peer asks first. Identity · environment · interaction · account · documentation, and
+  # for an admin a sixth section, admin.
   class Dashboard < ApiObject
     attribute :identity, wrap: User
     attribute :environment, wrap: DashboardEnvironment
     attribute :interaction, wrap: DashboardInteraction
     attribute :account, wrap: DashboardAccount
+    # Present only for an admin — so the Dashboard's shape is how a peer learns its own
+    # role. Reading it as anyone else raises MissingFieldError rather than guessing;
+    # branch on +me.identity.admin?+ instead.
+    attribute :admin, wrap: DashboardAdmin
     attribute :documentation, wrap: DashboardDocumentation
   end
 end

data/lib/basecradle/errors.rb

@@ -80,6 +80,9 @@ module BaseCradle
   # author (an admin may act on any task).
   class NotTaskAuthorError < ForbiddenError; end
 
+  # +not_an_admin+ — the surface is admin-only (contact messages and notes).
+  class NotAnAdminError < ForbiddenError; end
+
   # --- 404 --------------------------------------------------------------------------------
 
   # +not_found+ — no record exists for the given UUID (or it is hidden from you).
@@ -145,6 +148,9 @@ module BaseCradle
   # +payload_too_large+ — webhook ingest: the request body exceeds the maximum size.
   class PayloadTooLargeError < Error; end
 
+  # +binary_payload+ — webhook ingest: the request body is not UTF-8 text (HTTP 415).
+  class BinaryPayloadError < Error; end
+
   # --- the code => class registry ----------------------------------------------------------
 
   # Every API error is an RFC 9457 application/problem+json document with a stable,
@@ -158,6 +164,7 @@ module BaseCradle
     "not_timeline_owner" => NotTimelineOwnerError,
     "timeline_locked" => TimelineLockedError,
     "not_task_author" => NotTaskAuthorError,
+    "not_an_admin" => NotAnAdminError,
     "not_found" => NotFoundError,
     "task_not_pending" => TaskNotPendingError,
     "validation_failed" => ValidationError,
@@ -167,7 +174,8 @@ module BaseCradle
     "invalid_cursor" => InvalidCursorError,
     "invalid_filter" => InvalidFilterError,
     "endpoint_disabled" => EndpointDisabledError,
-    "payload_too_large" => PayloadTooLargeError
+    "payload_too_large" => PayloadTooLargeError,
+    "binary_payload" => BinaryPayloadError
   }.freeze
 
   class Error

data/lib/basecradle/headers.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+require_relative "rendering"
+
+module BaseCradle
+  # A recorded HTTP request's headers: the wire's own spelling, looked up
+  # case-insensitively. The platform records two kinds of inbound request verbatim — a
+  # webhook delivery (+WebhookEventHeaders+) and a contact-page submission
+  # (+ContactMessageHeaders+) — and both read through this one class's rules.
+  #
+  # A +Hash+ of exactly what the wire carried — one pair per header, +Content-Type+ and
+  # +Content-Length+ included — so iterating, +keys+, +to_h+, +to_json+ and +==+ all read
+  # the platform's own spelling and nothing is renamed. Only *lookup* folds case, because
+  # header names are case-insensitive by RFC and the platform does not preserve the
+  # sender's casing: it stores names canonicalized to Title-Case per segment
+  # (+X-Github-Delivery+, not +X-GitHub-Delivery+). So a vendor's published spelling finds
+  # the header it names, and so does any other casing of it:
+  #
+  #   event.content.headers["X-GitHub-Delivery"] # GitHub's own published spelling
+  #   event.content.headers["x-github-delivery"] # the lowercase form
+  #   event.content.headers["X-Github-Delivery"] # what the wire actually carried
+  #
+  # Every read that takes a header name folds: +fetch+, +dig+, +values_at+, +fetch_values+,
+  # +to_proc+ and +key?+ (with +has_key?+, +include?+ and +member?+). A header that was
+  # genuinely not sent is *absent*, never +nil+ — +[]+ and a fallback-less +fetch+ or
+  # +fetch_values+ raise +KeyError+ naming the headers that did arrive, while +fetch+ with
+  # a fallback, +dig+ and +values_at+ answer for it the way +Hash+ does.
+  #
+  # The methods that *reshape* the hash rather than read one name — +slice+, +except+,
+  # +select+, +transform_values+ — and the mutators are left exactly as +Hash+ defines
+  # them: case-sensitive, on the platform's own spelling. This is a read of one request
+  # that already happened. Converting away from this type gives up the folding too
+  # (+to_h+, <tt>{**headers}</tt>, and anything else that hands back a plain +Hash+);
+  # +merge+ and +dup+ keep it.
+  #
+  # What it does *not* print is the values: +inspect+, +to_s+ and +pp+ render the header
+  # names alone, because these are the sender's headers and one of them may be the
+  # sender's credential. Every read is unaffected — and so is +to_json+, which still
+  # emits the request verbatim. Converting away from this type gives the redaction up
+  # exactly as it gives up the folding, and for the same reason: +slice+, +except+,
+  # +select+, +transform_values+ and +to_h+ hand back a plain +Hash+, whose +inspect+
+  # prints pairs.
+  class RequestHeaders < Hash
+    # Hash brings its own render, and a header value is another party's credential. The
+    # module puts this class back under the SDK-wide rule; it sits between this class and
+    # Hash in the ancestor chain, so all three doors resolve to it.
+    include RendersNamesOnly
+
+    # Hash's own exact-match membership, kept under a private name before the case-folding
+    # +key?+ below takes the name: a caller who wrote the wire's own spelling is answered
+    # without a scan, and it is the tiebreak if a derived copy holds two casings of one
+    # name.
+    alias_method :exact_key?, :key?
+    private :exact_key?
+
+    NO_FALLBACK = Object.new.freeze
+    private_constant :NO_FALLBACK
+
+    # +client:+ is unused — headers carry no verbs — but every wrapped model is built with
+    # it (see ApiObject.attribute's +wrap:+), so it is accepted.
+    def initialize(data, client: nil)
+      super()
+      update(data)
+    end
+
+    # The header's value, matched case-insensitively. Raises +KeyError+ when no casing of
+    # the name was delivered.
+    def [](name)
+      wire = wire_name(name)
+      wire.nil? ? raise_missing(name) : super(wire)
+    end
+
+    # Hash-like: the value, or the fallback — a default argument, or a block, which is
+    # handed the name as written — when the header was not delivered. With no fallback it
+    # behaves like +[]+.
+    def fetch(name, fallback = NO_FALLBACK, &block)
+      wire = wire_name(name)
+      return super(wire) if wire
+      return yield(name) if block
+      return fallback unless fallback.equal?(NO_FALLBACK)
+
+      raise_missing(name)
+    end
+
+    # Did this request carry the header, under any casing?
+    def key?(name)
+      !wire_name(name).nil?
+    end
+    alias_method :has_key?, :key?
+    alias_method :include?, :key?
+    alias_method :member?, :key?
+
+    # Ruby's nil-returning read, case folded: the value, or +nil+ for a header that was
+    # not delivered.
+    def dig(name, *rest)
+      wire = wire_name(name)
+      wire.nil? ? nil : super(wire, *rest)
+    end
+
+    # Several headers at once, folded the same way — +nil+ for one that was not delivered,
+    # as +Hash+ answers for a key it has no value for.
+    def values_at(*names)
+      names.map { |name| dig(name) }
+    end
+
+    # As +values_at+, but a header that was not delivered raises, exactly as +fetch+ does.
+    def fetch_values(*names, &block)
+      names.map { |name| block ? fetch(name, &block) : fetch(name) }
+    end
+
+    # +&headers+ — a header name to its value, folded, +nil+ for one not delivered.
+    def to_proc
+      ->(name) { dig(name) }
+    end
+
+    private
+
+    # The header *names* this request carried, and none of their values.
+    #
+    # +Hash+'s own +inspect+ prints every pair, and these headers are the *sender's*,
+    # stored verbatim by the platform: a sender that authenticates its POST to an ingest
+    # URL puts its credential in one of them, and a contact-page visitor's browser may
+    # carry its own cookies or tokens. So +logger.debug(event.content.headers)+ or
+    # +logger.debug(message.headers)+ would write another party's secret into our logs.
+    #
+    # Only the human-facing render changes. Every *read* is untouched and still
+    # wire-exact: lookups, +fetch+, +each+, +keys+, +to_h+, +to_json+, +==+.
+    #
+    # Names are sorted by their string form — a derived copy can hold a key that never
+    # came off the wire, and a mixed-type +keys+ has no natural order otherwise.
+    #
+    # +nil+ for a request the platform recorded with no headers at all, so it renders as
+    # the bare class. That is asked of the hash, not of the joined string: a request
+    # carrying a single header whose *name* is the empty string joins to "" and must stay
+    # distinguishable from one carrying nothing.
+    def render_body
+      return nil if empty?
+
+      keys.sort_by(&:to_s).join(", ")
+    end
+
+    # The wire's own spelling of +name+, or nil if no casing of it was delivered. Anything
+    # but a String is not a header name, so it is never matched rather than being coerced
+    # into one: +headers[:host]+ finds nothing, and so misses like any other absent name.
+    # Keys are type-checked too — +merge+ hands back one of these, so a caller's derived
+    # copy can hold a key that never came off the wire.
+    def wire_name(name)
+      return nil unless name.is_a?(String)
+      return name if exact_key?(name)
+
+      each_key { |wire| return wire if wire.is_a?(String) && wire.casecmp?(name) }
+      nil
+    end
+
+    def raise_missing(name)
+      raise KeyError.new(
+        "No #{name.inspect} header on this request. Header names are matched " \
+        "case-insensitively, so no casing of it was sent either. " \
+        "Headers present: #{keys.sort_by(&:to_s).inspect}",
+        receiver: self, key: name
+      )
+    end
+  end
+end

data/lib/basecradle/rendering.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module BaseCradle
+  # Print what an object *is*, never what it holds.
+  #
+  # Every renderable object in this SDK follows one rule — a render shows field names and
+  # never field values — and the rule is what keeps secrets out of logs, REPL transcripts,
+  # exception messages and +p+ calls. It is load-bearing in three separate places:
+  # +Client+ holds a live +bc_uat_+ token; a +WebhookEventHeaders+ holds whatever an
+  # inbound sender put in its headers, which is another party's credential; and an
+  # +ApiObject+ holds a record's values, including an endpoint's +ingest_url+.
+  #
+  # The rule used to exist as three hand-rolled copies of the same three methods, with no
+  # fourth class ever being asked the question. That is exactly how the leak in 0.10.2
+  # arrived: +WebhookEventHeaders+ was added as a +Hash+ descendant, +Hash+ brought its
+  # own render, and every value printed with the suite green. Here it is one module, so a
+  # class added later either includes it or fails the reflective guard in
+  # +test/basecradle/rendering_test.rb+.
+  #
+  # Three doors, because a render arrives through three:
+  #
+  # - +inspect+ — +p+, a REPL echo, an exception's backtrace context, a nested +inspect+.
+  # - +to_s+ — string interpolation and +puts+, which is the door people reach for without
+  #   thinking about it. +Hash+ aliases +to_s+ to its *own* +inspect+ as one shared method
+  #   entry, so overriding +inspect+ alone leaves <tt>"#{headers}"</tt> printing values.
+  # - +pretty_print+ — +pp+. +pp+ uses an object's own +inspect+ when it defines one, which
+  #   is why an +ApiObject+ was already safe here and only a +Hash+ descendant was not;
+  #   delegating makes that a property of the module rather than a coincidence of which
+  #   superclass a class happens to have.
+  #
+  # +to_s+ is late-bound to +inspect+ rather than written <tt>alias to_s inspect</tt>: an
+  # alias copies the method body at alias time, so a subclass that redacts more in
+  # +inspect+ would be bypassed by interpolation.
+  module RendersNamesOnly
+    def inspect
+      body = render_body
+      body.nil? ? "#<#{self.class}>" : "#<#{self.class} #{body}>"
+    end
+
+    def to_s
+      inspect
+    end
+
+    def pretty_print(printer)
+      printer.text(inspect)
+    end
+
+    private
+
+    # What goes inside the angle brackets after the class name — names, never values.
+    # Includers supply it.
+    #
+    # +nil+ means "there is nothing to show" and renders the bare <tt>#<Class></tt>;
+    # anything else is rendered after a space, the empty string included. That
+    # distinction is not pedantry: a webhook delivery carrying one header whose *name* is
+    # the empty string is not the same delivery as one carrying no headers, and folding
+    # the two would report a header that arrived as a header that did not. So emptiness
+    # is the includer's question about its own contents, never this module's question
+    # about the string it was handed.
+    #
+    # The default raises rather than returning something bland, because a silent fallback
+    # would render an object as its class name alone and look deliberate; this SDK would
+    # rather fail in the test that includes the module.
+    def render_body
+      raise NotImplementedError,
+            "#{self.class} includes BaseCradle::RendersNamesOnly but defines no " \
+            "#render_body, so there is nothing for #inspect to print. Supply one " \
+            "returning field names — never field values."
+    end
+  end
+end

data/lib/basecradle/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module BaseCradle
-  VERSION = "0.10.3"
+  VERSION = "0.11.0"
 end

data/lib/basecradle/webhooks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "api_object"
+require_relative "headers"
 require_relative "items"
 require_relative "serialization"
 require_relative "user"
@@ -73,169 +74,9 @@ module BaseCradle
     end
   end
 
-  # One delivery's request headers: the wire's own spelling, looked up case-insensitively.
-  #
-  # A +Hash+ of exactly what the wire carried — one pair per header, +Content-Type+ and
-  # +Content-Length+ included — so iterating, +keys+, +to_h+, +to_json+ and +==+ all read
-  # the platform's own spelling and nothing is renamed. Only *lookup* folds case, because
-  # header names are case-insensitive by RFC and the platform does not preserve the
-  # sender's casing: it stores names canonicalized to Title-Case per segment
-  # (+X-Github-Delivery+, not +X-GitHub-Delivery+). So a vendor's published spelling finds
-  # the header it names, and so does any other casing of it:
-  #
-  #   event.content.headers["X-GitHub-Delivery"] # GitHub's own published spelling
-  #   event.content.headers["x-github-delivery"] # the lowercase form
-  #   event.content.headers["X-Github-Delivery"] # what the wire actually carried
-  #
-  # Every read that takes a header name folds: +fetch+, +dig+, +values_at+, +fetch_values+,
-  # +to_proc+ and +key?+ (with +has_key?+, +include?+ and +member?+). A header that was
-  # genuinely not delivered is *absent*, never +nil+ — +[]+ and a fallback-less +fetch+ or
-  # +fetch_values+ raise +KeyError+ naming the headers that did arrive, while +fetch+ with
-  # a fallback, +dig+ and +values_at+ answer for it the way +Hash+ does.
-  #
-  # The methods that *reshape* the hash rather than read one name — +slice+, +except+,
-  # +select+, +transform_values+ — and the mutators are left exactly as +Hash+ defines
-  # them: case-sensitive, on the platform's own spelling. This is a read of one delivery
-  # that already happened. Converting away from this type gives up the folding too
-  # (+to_h+, <tt>{**headers}</tt>, and anything else that hands back a plain +Hash+);
-  # +merge+ and +dup+ keep it.
-  #
-  # What it does *not* print is the values: +inspect+, +to_s+ and +pp+ render the header
-  # names alone, because these are the sender's headers and one of them may be the
-  # sender's credential. Every read is unaffected — and so is +to_json+, which still
-  # emits the delivery verbatim. Converting away from this type gives the redaction up
-  # exactly as it gives up the folding, and for the same reason: +slice+, +except+,
-  # +select+, +transform_values+ and +to_h+ hand back a plain +Hash+, whose +inspect+
-  # prints pairs.
-  class WebhookEventHeaders < Hash
-    # Hash's own exact-match membership, kept under a private name before the case-folding
-    # +key?+ below takes the name: a caller who wrote the wire's own spelling is answered
-    # without a scan, and it is the tiebreak if a derived copy holds two casings of one
-    # name.
-    alias_method :exact_key?, :key?
-    private :exact_key?
-
-    NO_FALLBACK = Object.new.freeze
-    private_constant :NO_FALLBACK
-
-    # +client:+ is unused — headers carry no verbs — but every wrapped model is built with
-    # it (see ApiObject.attribute's +wrap:+), so it is accepted.
-    def initialize(data, client: nil)
-      super()
-      update(data)
-    end
-
-    # The header's value, matched case-insensitively. Raises +KeyError+ when no casing of
-    # the name was delivered.
-    def [](name)
-      wire = wire_name(name)
-      wire.nil? ? raise_missing(name) : super(wire)
-    end
-
-    # Hash-like: the value, or the fallback — a default argument, or a block, which is
-    # handed the name as written — when the header was not delivered. With no fallback it
-    # behaves like +[]+.
-    def fetch(name, fallback = NO_FALLBACK, &block)
-      wire = wire_name(name)
-      return super(wire) if wire
-      return yield(name) if block
-      return fallback unless fallback.equal?(NO_FALLBACK)
-
-      raise_missing(name)
-    end
-
-    # Did this delivery carry the header, under any casing?
-    def key?(name)
-      !wire_name(name).nil?
-    end
-    alias_method :has_key?, :key?
-    alias_method :include?, :key?
-    alias_method :member?, :key?
-
-    # Ruby's nil-returning read, case folded: the value, or +nil+ for a header that was
-    # not delivered.
-    def dig(name, *rest)
-      wire = wire_name(name)
-      wire.nil? ? nil : super(wire, *rest)
-    end
-
-    # Several headers at once, folded the same way — +nil+ for one that was not delivered,
-    # as +Hash+ answers for a key it has no value for.
-    def values_at(*names)
-      names.map { |name| dig(name) }
-    end
-
-    # As +values_at+, but a header that was not delivered raises, exactly as +fetch+ does.
-    def fetch_values(*names, &block)
-      names.map { |name| block ? fetch(name, &block) : fetch(name) }
-    end
-
-    # +&headers+ — a header name to its value, folded, +nil+ for one not delivered.
-    def to_proc
-      ->(name) { dig(name) }
-    end
-
-    # The header *names* this delivery carried, and none of their values.
-    #
-    # +Hash+'s own +inspect+ prints every pair, and these headers are the *sender's*,
-    # stored verbatim by the platform: a sender that authenticates its POST to an ingest
-    # URL puts its credential in one of them, so +logger.debug(event.content.headers)+
-    # would write another party's secret into our logs. Every other renderable object in
-    # this SDK is already safe by one rule — +ApiObject#inspect+ prints field names, never
-    # values — and this is the one class that sat outside it, because +Hash+ brought its
-    # own render.
-    #
-    # Only the human-facing render changes. Every *read* is untouched and still
-    # wire-exact: lookups, +fetch+, +each+, +keys+, +to_h+, +to_json+, +==+.
-    #
-    # Names are sorted, as +ApiObject#inspect+ sorts its fields and as the +KeyError+ a
-    # missing header raises already lists the ones that did arrive.
-    def inspect
-      return "#<#{self.class}>" if empty?
-
-      "#<#{self.class} #{keys.sort_by(&:to_s).join(', ')}>"
-    end
-
-    # +Hash+ aliases +to_s+ to its *own* +inspect+ — one shared method entry — so
-    # overriding +inspect+ alone would leave <tt>"#{headers}"</tt> and +puts headers+
-    # printing every value. Late-bound rather than +alias to_s inspect+, so a subclass
-    # that redacts more is not bypassed by interpolation (as +Client#to_s+ is).
-    def to_s
-      inspect
-    end
-
-    # +pp+ reaches for +pretty_print+, and +Hash+ brings one that prints the pairs — the
-    # same leak through the one door +inspect+ does not cover. Delegating puts +pp+ back
-    # on the SDK-wide rule: +pp+ uses an object's own +inspect+ when it defines one, which
-    # is why every +ApiObject+ is already safe here and only a +Hash+ descendant was not.
-    def pretty_print(printer)
-      printer.text(inspect)
-    end
-
-    private
-
-    # The wire's own spelling of +name+, or nil if no casing of it was delivered. Anything
-    # but a String is not a header name, so it is never matched rather than being coerced
-    # into one: +headers[:host]+ finds nothing, and so misses like any other absent name.
-    # Keys are type-checked too — +merge+ hands back one of these, so a caller's derived
-    # copy can hold a key that never came off the wire.
-    def wire_name(name)
-      return nil unless name.is_a?(String)
-      return name if exact_key?(name)
-
-      each_key { |wire| return wire if wire.is_a?(String) && wire.casecmp?(name) }
-      nil
-    end
-
-    def raise_missing(name)
-      raise KeyError.new(
-        "No #{name.inspect} header on this delivery. Header names are matched " \
-        "case-insensitively, so no casing of it was delivered either. " \
-        "Headers present: #{keys.sort_by(&:to_s).inspect}",
-        receiver: self, key: name
-      )
-    end
-  end
+  # One delivery's request headers, exactly as the sender sent them — read through
+  # RequestHeaders' rules: case-insensitive lookup, a render of names and never values.
+  class WebhookEventHeaders < RequestHeaders; end
 
   # One inbound delivery: what was sent, and the two facts about the endpoint as it was at
   # the moment of receipt. Everything in the event's embedded endpoint is *current*; these

data/lib/basecradle.rb

@@ -9,6 +9,8 @@ require_relative "basecradle/pagination"
 require_relative "basecradle/items"
 require_relative "basecradle/webhooks"
 require_relative "basecradle/sessions"
+require_relative "basecradle/headers"
+require_relative "basecradle/contact_messages"
 require_relative "basecradle/timeline"
 require_relative "basecradle/timelines"
 require_relative "basecradle/client"
@@ -18,8 +20,9 @@ require_relative "basecradle/client"
 # same API (https://basecradle.com).
 #
 # Start with a client: +BaseCradle::Client.new+ (token from BASECRADLE_TOKEN) or
-# +BaseCradle::Client.login(email_address:, password:)+. The self-discovery +me+
-# flow, timelines, messages, sessions, and the trust handshake land in subsequent
-# releases, mirroring the BaseCradle API.
+# +BaseCradle::Client.login(email_address:, password:)+. From there, +bc.me+ answers
+# "who am I?", and every other surface of the BaseCradle API hangs off the client:
+# timelines and their messages, assets, tasks and webhooks, your own sessions, and the
+# users directory with its trust handshake.
 module BaseCradle
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.10.3
+  version: 0.11.0
 platform: ruby
 authors:
 - Drawk Kwast
@@ -22,10 +22,13 @@ files:
 - lib/basecradle.rb
 - lib/basecradle/api_object.rb
 - lib/basecradle/client.rb
+- lib/basecradle/contact_messages.rb
 - lib/basecradle/dashboard.rb
 - lib/basecradle/errors.rb
+- lib/basecradle/headers.rb
 - lib/basecradle/items.rb
 - lib/basecradle/pagination.rb
+- lib/basecradle/rendering.rb
 - lib/basecradle/serialization.rb
 - lib/basecradle/sessions.rb
 - lib/basecradle/timeline.rb