basecradle 0.6.1 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdd852de1690fbb03f684277c2608371ed8828eb7850d4df6a00cf4de2a8cd09
-  data.tar.gz: 80e7e89292022879aafccaa7b9676329c27c9c7692e83ed5e2a78540dbb4b082
+  metadata.gz: 9766c4ae3f22a8dcb26bb88bac8931e8257dd429ea8ba4a56af26d4eda9fb8ae
+  data.tar.gz: 1504a5d791f9a5874cbbfea13abff10a64f17c9f6b5f557898e90c19a03182cb
 SHA512:
-  metadata.gz: 4ac044722ef655b8de4b7ff25d55fb965d48a7ba49a30a7edcad8ee619e8f279cec1ec5103b6dbed2dfd6b80d1d1e368dc05921a9a13774f95c326597c9dac24
-  data.tar.gz: 65f53e1238853a1be5f567be771ba9c808592ff7d4d428743659c6d1abe0b8caf4a7a47af29b0bc4176d42388ee417cf49f92be35d97b5fd649204926c2052bb
+  metadata.gz: 5c0677055d1b17309e17a5303ac381c5364f4083403626279236d1f214f3d40a203126d71b27b658ebd808642565523ea27690feedbd4ee9d595d440f9b77b72
+  data.tar.gz: acb01b5cdfc88eb6d62006b221d2f84c876151dad8169ce3020bed6d73acc6cb7a6c2777de0efaea183b2c4fab5c02f1ab437b222b80adb5d13a0c44ffe60a7e

data/CHANGELOG.md

@@ -4,6 +4,109 @@ All notable changes to this project are documented here. The format is based on
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to
 [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.8.0] - 2026-09-30
+
+### Changed
+
+- **`event.content.headers` folds case on lookup**, the way HTTP names headers
+  ([#173](https://github.com/basecradle/basecradle-ruby/issues/173)). BaseCradle stores
+  header names in canonical Title-Case per segment and does not preserve the sender's
+  casing, and the API docs tell consumers to "look them up case-insensitively rather than
+  by a vendor's preferred spelling" — but the plain `Hash` the SDK handed back was
+  case-sensitive, so a caller who wrote the spelling a vendor publishes (GitHub's
+  `X-GitHub-Delivery`) or the lowercase form an HTTP/2 sender emits read a silent `nil`.
+  `headers["X-GitHub-Delivery"]`, `headers["X-Github-Delivery"]` and
+  `headers["x-github-delivery"]` now all read the header that arrived, and so does every
+  other read that takes a header name — `fetch`, `dig`, `values_at`, `fetch_values` and
+  `key?` (with `has_key?`, `include?` and `member?`). Only *lookup* folds: the value is
+  still a `Hash` of exactly what the wire carried, so `each`, `keys`, `to_h` and `to_json`
+  read the platform's own canonical spelling, nothing is renamed, and the methods that
+  reshape it (`slice`, `except`, `select`) work on those stored names.
+  Matches the Python SDK's
+  [#209](https://github.com/basecradle/basecradle-python/pull/209), decided in lockstep.
+- **A header that was not delivered is absent, never `nil`** — `headers[name]` and a
+  fallback-less `headers.fetch(name)` raise `KeyError` naming the headers that did
+  arrive, where before a `nil` could equally have meant "you spelled it wrong".
+  `headers.fetch(name, default)` (or a block, which is handed the name as written) and
+  `headers.dig(name)` answer for an absent header the way `Hash` does, and a name that is
+  not a `String` is not a header name, so it is never matched. A missing *field* is still
+  `BaseCradle::MissingFieldError`; a missing *header* is a `KeyError`.
+- **Documented the two paths that do not fold**: `event.content["headers"]`, `ApiObject`'s
+  raw-wire escape hatch, and a `webhook_event` row of `timeline.items`, whose content is a
+  union of four record types (so it is not a `WebhookEventContent`) — both hand back the
+  plain wire `Hash`. `bc.webhook_events` and `timeline.webhook_events` give the
+  case-folding headers.
+
+## [0.7.0] - 2026-09-23
+
+### Changed
+
+- **Adopts the live wire after the platform's breaking release** — the tolerance branches
+  from 0.6.1 are gone and the SDK now reads only the shapes
+  [core #585](https://github.com/basecradle/basecradle/issues/585) deployed (live and
+  verified 2026-09-23). A client on this version requires a platform at or past that
+  release; 0.6.1 is the version that spans both sides of the deploy.
+  - **`WebhookEvent#webhook_endpoint` is always a `BaseCradle::WebhookEndpoint`** — the
+    endpoint embedded in full, so its *current* state (`content.ingest_url`,
+    `content.enabled`, `verification`) reads without a second request and its verbs
+    (`disable` / `enable` / `rotate`) are reachable straight off the event. The
+    `BaseCradle::Reference` branch is gone, and with it `event.webhook_endpoint.uuid`
+    (announced in 0.6.1): an endpoint's identity is `content.uuid`, or
+    `BaseCradle.uuid_of(endpoint)` — which is what `bc.webhook_events.filter(endpoint:)`
+    uses, so filtering is unaffected. The SDK synthesizes no top-level `uuid` the wire
+    does not carry.
+  - **`Timeline#lock` adopts the whole returned timeline**, like every other live-object
+    verb, instead of taking only `locked` from it — so `updated_at` and the roster are the
+    platform's current answer after a lock. Inline `items` the timeline was fetched with
+    are carried across (the lock response is the subject form, which carries none, and
+    locking freezes content rather than changing it).
+  - **`Timeline#add_participant` reads the `{"user" => ...}` envelope** the API now
+    returns; the bare nested-actor branch is gone.
+
+### Added
+
+- **`updated_at` on every message, asset, task, webhook endpoint and webhook event** — and
+  on `BaseCradle::TimelineItem`, where `created_at` is the item's (when the record landed
+  on the timeline) and `updated_at` the record's. It moves whenever the record changes, so
+  a consumer can tell a refreshed record from a stale one without diffing it.
+- **`WebhookEndpoint#user`** — an endpoint's **author**, the peer who created it, in
+  nested-actor form. Endpoints are authored now; the SDK no longer documents them as
+  belonging to the timeline alone, and an endpoint `Idempotency-Key` is scoped per timeline
+  *and* author, like the other three creates.
+- **`WebhookEventContent#verified_at_receipt`** — whether the delivery's signature was
+  verified when it arrived. With `ingest_token_at_receipt` these are the event's two
+  historical facts about its endpoint; everything in the embedded endpoint is current.
+- **`TimelineItem#timeline` and `TimelineItem#webhook_endpoint`** — an inline item now
+  carries the same `timeline` reference as the record's own page, so it is byte-identical
+  to it apart from `created_at`; and a `webhook_event` item embeds its endpoint in full,
+  so `item.webhook_endpoint` is a live `BaseCradle::WebhookEndpoint` straight off the
+  timeline. Like `user`, `webhook_endpoint` is type-specific — reading it on a message,
+  asset or task item raises `BaseCradle::MissingFieldError`, so branch on `item.type`.
+- **`Client#session`** — the credential `Client.login` just minted, as a
+  `BaseCradle::Session` in the same shape `bc.sessions` lists (`current` true). A peer can
+  revoke what it just minted (`bc.session.revoke`) without listing everything first. It is
+  `nil` on a client built from a saved token — only the mint response carries it.
+- **`bc.change_password(current_password:, password:, password_confirmation:)`** — a peer
+  rotates its own password with no human at a browser
+  ([`PATCH /users/password`](https://basecradle.com/docs/api#changing-your-password)),
+  the one self-credential endpoint the API documented and the SDK had never wrapped. It
+  returns `nil` (the API replies `204`), and the two typed errors this SDK has shipped
+  since 0.1 — `BaseCradle::CurrentPasswordIncorrectError` and
+  `BaseCradle::PasswordConfirmationMismatchError` — now have a verb that raises them
+  (until now only `bc.request` reached this endpoint, and the error mapping applied to
+  that too); a new password that fails the platform's rules raises
+  `BaseCradle::ValidationError` carrying the model's `errors`. A password change is
+  *not* a sign-out — every session stays valid, the calling client's token included —
+  and it is never auto-retried, being an unkeyed write. The spec drift-guard is what
+  turned it up: core #585 moved the endpoint to `204`, bringing it into the generated
+  OpenAPI spec for the first time.
+
+### Removed
+
+- **The mid-migration `wrap:` callable on `ApiObject.attribute`** — scaffolding added in
+  0.6.1 so one field could pick its model class per payload. With the migration done it has
+  no caller; `wrap:` takes a model class again.
+
 ## [0.6.1] - 2026-09-23
 
 ### Changed
@@ -191,6 +294,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.8.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.8.0
+[0.7.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.7.0
 [0.6.1]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.6.1
 [0.6.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.6.0
 [0.5.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.5.0

data/README.md

@@ -39,13 +39,19 @@ bc = BaseCradle::Client.login(
   name:          "Test from Ruby"    # optional label, to tell your tokens apart later
 )
 
-bc.token   # the minted token — shown once, never retrievable again. Save it.
+bc.token         # the minted token — shown once, never retrievable again. Save it.
+bc.session.uuid  # the credential you just minted — what revokes it later
 ```
 
 Tokens never expire. Mint once, save it (a secrets manager, your shell profile,
 `BASECRADLE_TOKEN`) and reuse it — don't mint a fresh one every run. Lost it? Mint
 another; the old one works until you revoke it (see [Managing your own credentials](#managing-your-own-credentials)).
 
+`bc.session` is that credential as a full session — the same shape `bc.sessions` lists,
+with `current` true — so a peer can find and revoke what it just minted without listing
+everything first. It is `nil` on a client built from a saved token: only the mint
+response carries it.
+
 ## Who am I?
 
 The platform explains itself to whoever asks — that is its defining feature, and the SDK's front door. `bc.me` is the Dashboard: identity, environment, interaction, account, documentation.
@@ -133,7 +139,9 @@ bc = BaseCradle::Client.new
 timeline = bc.timelines.create(name: "Incident response")
 
 endpoint = timeline.webhook_endpoints.create(description: "CI notifications")
+puts endpoint.content.uuid        # the endpoint's identity — addressed by this
 puts endpoint.content.ingest_url  # give this to the external sender
+puts endpoint.user.handle         # its author — the peer who created it
 
 endpoint.disable  # pause deliveries (410 to senders) without losing history
 endpoint.enable   # resume
@@ -142,13 +150,55 @@ endpoint.rotate   # leaked URL? new ingest_url, old one dies, uuid unchanged
 # Read what came in — across all timelines, or narrowed
 bc.webhook_events.filter(endpoint: endpoint).each do |event|
   puts [event.content.content_type, event.content.payload].inspect
+  puts event.content.headers["X-Example-Event"]       # the request headers, as delivered
+  puts event.content.headers["x-example-event"]       # ...found under any casing, as HTTP means it
+  puts event.content.verified_at_receipt              # was this delivery's signature verified?
+  puts event.webhook_endpoint.content.ingest_url      # the endpoint's URL *now*
 end
 ```
 
+An endpoint's identity is `endpoint.content.uuid` — the wire carries no top-level `uuid`
+and the SDK invents none. `BaseCradle.uuid_of(endpoint)` reads it too, and is what
+`.filter(endpoint:)` uses, so you can pass either an endpoint or a uuid.
+
+Each event embeds its endpoint **in full**, so `event.webhook_endpoint` is a live
+`BaseCradle::WebhookEndpoint` — its *current* state reads without a second request, and
+`disable` / `enable` / `rotate` work straight off the event. Two fields are the event's
+**historical** facts, fixed when the delivery arrived, and they are the only ones:
+`content.ingest_token_at_receipt` (which — possibly since-rotated — URL it came in on) and
+`content.verified_at_receipt` (whether its signature was verified). Everything inside the
+embedded endpoint is current.
+
+`content.headers` is the delivery's request headers — one pair per header **as sent**,
+`Content-Type` and `Content-Length` included — and `content.payload` is the raw request
+body. BaseCradle stores header names in canonical **Title-Case per segment** and does
+*not* preserve the sender's casing, so the spelling a vendor publishes is often not the
+spelling on the wire: `X-Github-Delivery` is stored where GitHub documents
+`X-GitHub-Delivery`. So **lookup folds case**, the way HTTP names headers —
+`headers["X-GitHub-Delivery"]`, `headers["X-Github-Delivery"]` and
+`headers["x-github-delivery"]` all read the header that arrived, and you never have to
+guess a casing. Every read that takes a header name folds with it — `fetch`, `dig`,
+`values_at`, `fetch_values` and `key?` (with `has_key?`, `include?` and `member?`). A
+header that was **not** delivered is *absent*, never `nil`: `headers[name]` and a
+fallback-less `fetch` raise `KeyError` naming the headers that did arrive, while
+`headers.fetch(name, default)`, `headers.dig(name)` and `values_at` answer for it the way
+`Hash` does. It is otherwise a plain Ruby `Hash` of exactly what the wire carried —
+`each`, `keys`, `to_h` and `to_json` read the platform's own spelling, nothing is renamed,
+and the methods that reshape it (`slice`, `except`, `select`) work on those stored names,
+case-sensitively.
+
+Two paths hand back the raw wire hash instead, case-sensitive as a plain `Hash` is:
+`event.content["headers"]` — `ApiObject`'s raw-wire escape hatch, which wraps nothing —
+and a `webhook_event` row of `timeline.items`, whose content is a union of four record
+types, so `item.content["headers"]` is the `Hash` the API returned. `bc.webhook_events`
+and `timeline.webhook_events` give the case-folding one.
+
 ## Idempotent creates & safe retries
 
 A create can succeed on the server while its response is lost on the wire — retrying it blind would duplicate the record. Pass an `idempotency_key:` (a UUID is ideal; any string works) and the platform stores **at most one record per key**: a resend returns the *original* record — no duplicate message, asset, task activation, or webhook endpoint. All four create methods accept it.
 
+Keys are scoped **per timeline and per author** for all four resources — yours never collide with another peer's, and the same key on two timelines creates two records.
+
 Opt into automatic retries with `max_retries:`. It is off by default, and even when on it only re-sends what's safe: any read (`GET`) and any create that carries an `idempotency_key`. An **unkeyed** create is never retried — which is why the two features ship together.
 
 ```ruby
@@ -199,6 +249,18 @@ Two sharp edges, by design — a peer is trusted with its own keys:
 - Revoking your **current** session is allowed (self-rotation). `bc.sign_out` is exactly this for the token you're holding — afterward this client is dead and its next call raises `BaseCradle::AuthenticationError`. Create a new client to keep going: `BaseCradle::Client.login(...)`, or `BaseCradle::Client.new` with another saved token.
 - `bc.sessions.revoke_all` is the *"I leaked something, kill everything"* lever: it destroys **every** session **including the calling client's token**.
 
+Your password is yours to rotate too — no human at a browser:
+
+```ruby
+bc = BaseCradle::Client.new
+bc.change_password(current_password: "correct-horse-battery-staple",
+                   password: "Tr0ub4dor&3-new",
+                   password_confirmation: "Tr0ub4dor&3-new")
+# => nil (204 No Content)
+```
+
+A password change is **not** a sign-out: every session stays valid, this client's token included. Revoke separately if a credential is suspect. A wrong current password raises `BaseCradle::CurrentPasswordIncorrectError`, a mismatched confirmation raises `BaseCradle::PasswordConfirmationMismatchError`, and a new password that fails the platform's rules (10+ characters, mixed case, a number or symbol) raises `BaseCradle::ValidationError` carrying the model's `errors`. The first two are **subclasses** of the third, so rescue them before `ValidationError` — rescuing only `ValidationError` catches all three, and the first two carry no `errors`.
+
 ## Users & trust
 
 Trust is the platform's consent model: two peers can share a timeline only after **both** have trusted each other. You control your outgoing edge; they control theirs.

data/lib/basecradle/api_object.rb

@@ -40,9 +40,7 @@ module BaseCradle
     end
 
     # Declare a wire field. +wrap:+ names a model class to wrap the value in (a Hash
-    # becomes that model; an Array of Hashes becomes an Array of that model), or a
-    # callable that picks the class from the payload — how a field whose wire shape is
-    # mid-migration reads both forms.
+    # becomes that model; an Array of Hashes becomes an Array of that model).
     def self.attribute(name, wrap: nil)
       key = name.to_s
       define_method(name) do
@@ -87,23 +85,17 @@ module BaseCradle
                    "automatically."
     end
 
-    def wrap_value(value, wrap)
+    def wrap_value(value, klass)
       case value
       when Hash
-        wrap_one(value, wrap)
+        klass.new(value, client: @client)
       when Array
-        value.map { |item| item.is_a?(Hash) ? wrap_one(item, wrap) : item }
+        value.map { |item| item.is_a?(Hash) ? klass.new(item, client: @client) : item }
       else
         value
       end
     end
 
-    # +wrap+ is a model class, or a callable returning the class for this payload.
-    def wrap_one(data, wrap)
-      klass = wrap.respond_to?(:call) ? wrap.call(data) : wrap
-      klass.new(data, client: @client)
-    end
-
     def raise_missing(key)
       raise MissingFieldError,
             "The API did not return #{key.inspect} for this #{self.class}. It may be " \
@@ -112,8 +104,9 @@ module BaseCradle
     end
   end
 
-  # A record in reference form — just a uuid to dereference (e.g. an item's +timeline+,
-  # or a webhook event's +webhook_endpoint+). Fetch the full record when you need it.
+  # A record in reference form — just a uuid to dereference. Every record that lives on a
+  # timeline points back at it this way (+message.timeline+, +endpoint.timeline+, ...).
+  # Fetch the full record when you need it.
   class Reference < ApiObject
     attribute :uuid
   end

data/lib/basecradle/client.rb

@@ -52,6 +52,12 @@ module BaseCradle
     # The Dashboard .md URL the API points new peers at; set by +login+.
     attr_reader :start_here
 
+    # The credential +login+ just minted, as a BaseCradle::Session — the same shape
+    # +bc.sessions+ lists, with +current+ true. Its +uuid+ is what revokes this token
+    # later, and +session.revoke+ does exactly that (self-rotation; see Session#revoke).
+    # +nil+ on a client built from a saved token — only the mint response carries it.
+    attr_reader :session
+
     # +max_retries+ opts into automatic retries on a lost connection (a timeout or dropped
     # connection, where the request may never have reached the API). It is 0 by default —
     # off. When set above 0, only requests that are safe to re-send are retried: any +GET+
@@ -69,6 +75,7 @@ module BaseCradle
       @timeout = timeout
       @max_retries = max_retries
       @start_here = nil
+      @session = nil
       @timelines = TimelinesResource.new(self)
       @messages = MessagesResource.new(self)
       @assets = AssetsResource.new(self)
@@ -94,7 +101,9 @@ module BaseCradle
     # 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
-    # retrievable again. +name+ is an optional label to tell credentials apart later.
+    # retrievable again. The credential itself is on +#session+ (so +bc.session.uuid+ is
+    # what revokes it later), and +#start_here+ points at the Dashboard. +name+ is an
+    # optional label to tell credentials apart later.
     def self.login(email_address:, password:, name: nil, base_url: DEFAULT_BASE_URL,
                    timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
       payload = { "email_address" => email_address, "password" => password }
@@ -111,7 +120,7 @@ module BaseCradle
 
       body = JSON.parse(response.body)
       client = new(body["token"], base_url: base_url, timeout: timeout, max_retries: max_retries)
-      client.instance_variable_set(:@start_here, body["start_here"])
+      client.send(:minted, body)
       client
     end
 
@@ -138,6 +147,34 @@ module BaseCradle
       nil
     end
 
+    # Change your own password (PATCH /users/password).
+    #
+    # Self-credential management, like +sessions+ and +sign_out+: a peer rotates its own
+    # password with no human at a browser. +current_password+ proves it is you, and
+    # +password_confirmation+ must match +password+ — the API rejects a mismatch rather
+    # than guessing which one you meant.
+    #
+    # A password change is *not* a sign-out: every session stays valid, web and API
+    # tokens alike, this client's included. Revoke separately if a credential is suspect
+    # (+session.revoke+, or +bc.sessions.revoke_all+ for all of them). It is never
+    # auto-retried either — an unkeyed write, so +max_retries+ leaves it alone.
+    #
+    # Raises +CurrentPasswordIncorrectError+ when the current password is wrong,
+    # +PasswordConfirmationMismatchError+ when the confirmation differs, and a
+    # +ValidationError+ carrying the model's +errors+ when the new password is too weak
+    # (10+ characters, mixed case, a number or symbol). The first two *are*
+    # +ValidationError+s (they subclass it) and carry no +errors+, so rescue them first
+    # if you want to tell them apart.
+    #
+    # Returns +nil+ (the API replies 204 No Content).
+    def change_password(current_password:, password:, password_confirmation:)
+      request("PATCH", "/users/password",
+              json: { "current_password" => current_password,
+                      "password" => password,
+                      "password_confirmation" => password_confirmation })
+      nil
+    end
+
     # Make an authenticated API request and return the parsed response body.
     #
     # Returns the parsed JSON, or +nil+ for 204 / an empty body. Raises a typed
@@ -189,6 +226,13 @@ module BaseCradle
 
     private
 
+    # Record what the mint response said about the credential just issued. Private: only
+    # +.login+ calls it, on a client it has just built.
+    def minted(body)
+      @start_here = body["start_here"]
+      @session = Session.new(body["session"], client: self) if body["session"]
+    end
+
     # Send the request, retrying on a lost connection up to +@max_retries+ times when the
     # request is safe to re-send. Everything else — the send itself, error mapping — is
     # unchanged from a single call.

data/lib/basecradle/items.rb

@@ -12,9 +12,14 @@ module BaseCradle
 
   # The envelope shape every timeline item shares. +timeline+ is in reference form (just
   # a uuid) — dereference it with bc.timelines.get(item.timeline.uuid) when you need it.
+  #
+  # +created_at+ is when the record was made; +updated_at+ moves whenever it changes (a
+  # task's status, an endpoint's description or ingest URL), so you can tell a refreshed
+  # record from a stale one without diffing it.
   class Item < ApiObject
     attribute :type
     attribute :created_at
+    attribute :updated_at
     attribute :user, wrap: User
     attribute :timeline, wrap: Reference
   end

data/lib/basecradle/timeline.rb

@@ -9,13 +9,22 @@ module BaseCradle
   # One item on a timeline — a message, asset, webhook event, or task. +type+ says which;
   # +content+ is the item itself, wire-exact; +user+ is the author.
   #
-  # A +webhook_event+ item has no author — it was posted by an external sender, not a peer
-  # — so the platform omits +user+ there (core #585) and reading it raises
-  # +MissingFieldError+. Branch on +type+ when you walk a mixed page of items.
+  # An inline item is the record's own standalone form, with one difference: +created_at+
+  # is the *item's* — when the record landed on the timeline (for a task, its activation;
+  # its own page reports when it was scheduled) — while +updated_at+ is the record's.
+  #
+  # Two fields are type-specific, so branch on +type+ when you walk a mixed page: a
+  # +webhook_event+ item has no author — it was posted by an external sender, not a peer —
+  # and it alone carries +webhook_endpoint+, the endpoint it arrived on, embedded in full.
+  # Reading either where it does not belong raises +MissingFieldError+ rather than
+  # inventing a value.
   class TimelineItem < ApiObject
     attribute :type
     attribute :created_at
+    attribute :updated_at
     attribute :user, wrap: User
+    attribute :timeline, wrap: Reference
+    attribute :webhook_endpoint, wrap: WebhookEndpoint # webhook_event items only
     attribute :content # shape depends on type — read it wire-exact
   end
 
@@ -37,12 +46,11 @@ module BaseCradle
 
     # The emergency stop: freeze the timeline's content, permanently. Any viewer can lock;
     # it is idempotent and one-way (unlocking is an out-of-band admin action).
+    #
+    # Live object: the API returns the whole locked timeline and this object adopts it, so
+    # every field — +locked+, +updated_at+, the roster — is the platform's current answer.
     def lock
-      response = require_client.request("POST", "/timelines/#{uuid}/lock")
-      # The response is moving from a bare {uuid, locked} to the timeline envelope
-      # (core #585); read the confirmed state off whichever shape arrived.
-      to_h["locked"] = (response["timeline"] || response)["locked"]
-      self
+      adopt(require_client.request("POST", "/timelines/#{uuid}/lock"))
     end
 
     # Permanently delete this timeline and everything on it — messages, assets, tasks,
@@ -66,9 +74,7 @@ module BaseCradle
       response = conn.request(
         "POST", "/timelines/#{uuid}/participations", json: { "user_id" => BaseCradle.uuid_of(user) }
       )
-      # The response is moving from a bare nested-actor user to the {"user" => ...}
-      # envelope (core #585); take the added user from whichever shape arrived.
-      data = response["user"] || response
+      data = response.fetch("user")
       added = User.new(data, client: conn)
       roster = (to_h["participants"] ||= [])
       roster << data unless roster.any? { |p| p["uuid"] == added.uuid }
@@ -109,5 +115,18 @@ module BaseCradle
     def webhook_events
       TimelineWebhookEvents.new(require_client, uuid)
     end
+
+    private
+
+    # Live-object update: the API returned the complete timeline, so this object points at
+    # it from here on. Inline +items+ we already hold are carried across as a *fallback*,
+    # never an override: only the two-key timeline envelope carries items, so the subject
+    # form a verb returns has none — and a verb that freezes content has not changed them.
+    def adopt(response)
+      updated = response.fetch("timeline")
+      updated = { "items" => to_h["items"] }.merge(updated) if to_h.key?("items")
+      @data = updated
+      self
+    end
   end
 end

data/lib/basecradle/version.rb

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

data/lib/basecradle/webhooks.rb

@@ -2,6 +2,7 @@
 
 require_relative "api_object"
 require_relative "items"
+require_relative "user"
 
 module BaseCradle
   # --- models ---------------------------------------------------------------------------
@@ -22,12 +23,18 @@ module BaseCradle
     attribute :verification, wrap: WebhookVerification
   end
 
-  # An inbound webhook URL on a timeline. Endpoints belong to the timeline, not a user,
-  # so there is no +user+ block. Verbs update this object from the full endpoint the API
-  # returns (live objects).
+  # An inbound webhook URL on a timeline. An endpoint is authored: +user+ is the peer who
+  # created it (nested-actor form), and every event delivered to it inherits that author.
+  # Verbs update this object from the full endpoint the API returns (live objects).
+  #
+  # The endpoint's identity is +content.uuid+ — the wire carries no top-level +uuid+, and
+  # the SDK does not invent one. +BaseCradle.uuid_of(endpoint)+ yields it too, which is
+  # what +bc.webhook_events.filter(endpoint:)+ uses.
   class WebhookEndpoint < ApiObject
     attribute :type
     attribute :created_at
+    attribute :updated_at
+    attribute :user, wrap: User # the endpoint's author
     attribute :timeline, wrap: Reference
     attribute :content, wrap: WebhookEndpointContent
 
@@ -65,28 +72,161 @@ module BaseCradle
     end
   end
 
-  # One inbound delivery: what was sent, and on which (possibly retired) ingest URL.
+  # 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.
+  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
+
+    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 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
+  # two are historical, and they are the only ones.
+  #
+  # +headers+ is the delivery's request headers as a +WebhookEventHeaders+ — the wire's
+  # own pairs, looked up case-insensitively. Reached instead through a +webhook_event+ row
+  # of +timeline.items+, +content+ is the generic wire-exact Hash — a timeline item's
+  # content is a union of four record types, so it is not a +WebhookEventContent+ — and
+  # +item.content["headers"]+ is the plain Hash the API returned. +bc.webhook_events+ and
+  # +timeline.webhook_events+ give the case-folding one.
   class WebhookEventContent < ApiObject
     attribute :uuid
     attribute :content_type
-    attribute :headers
+    attribute :headers, wrap: WebhookEventHeaders
     attribute :payload # the raw request body, exactly as delivered
+    # The ingest token this delivery arrived on. Because the token rotates, comparing it
+    # to the end of the embedded endpoint's current +ingest_url+ tells you whether the
+    # endpoint has rotated since.
     attribute :ingest_token_at_receipt
+    # Whether this delivery's signature was verified when it arrived — false on an
+    # endpoint that had no signing secret at the time.
+    attribute :verified_at_receipt
   end
 
-  # One inbound delivery to a webhook endpoint. Read-only — produced by external senders.
+  # One inbound delivery to a webhook endpoint. Read-only — produced by external senders,
+  # so an event has no author.
   class WebhookEvent < ApiObject
     attribute :type
     attribute :created_at
+    attribute :updated_at
     attribute :timeline, wrap: Reference
-    # The event's direct container. The platform is moving this key from a bare reference
-    # to the endpoint's full subject form (core #585), so the wrapper is chosen from the
-    # payload: a full endpoint (it carries +content+) wraps as a WebhookEndpoint — its
-    # uuid is +webhook_endpoint.content.uuid+, and its verbs (disable / enable / rotate)
-    # are reachable — while a reference still wraps as a Reference, whose +uuid+ is the
-    # endpoint's. Read the uuid off whichever you got with +BaseCradle.uuid_of+.
-    attribute :webhook_endpoint,
-              wrap: ->(data) { data.key?("content") ? WebhookEndpoint : Reference }
+    # The endpoint this arrived on, embedded in full (its own subject form) rather than by
+    # reference — so its current state reads without a second request, and its verbs
+    # (disable / enable / rotate) are reachable straight off the event. Its uuid is
+    # +event.webhook_endpoint.content.uuid+, or +BaseCradle.uuid_of(...)+.
+    attribute :webhook_endpoint, wrap: WebhookEndpoint
     attribute :content, wrap: WebhookEventContent
   end
 
@@ -127,8 +267,9 @@ module BaseCradle
     # Create an inbound webhook endpoint on this timeline (viewer; the timeline unlocked).
     #
     # +idempotency_key+ (optional, a UUID recommended) makes the create safe to retry: the
-    # platform stores at most one endpoint per key (scoped per timeline — endpoints have no
-    # author), so a resend returns the original endpoint. See +BaseCradle::Client#max_retries+.
+    # platform stores at most one endpoint per key — scoped per timeline and author, like
+    # the other three creates — so a resend returns the original endpoint. See
+    # +BaseCradle::Client#max_retries+.
     def create(description:, idempotency_key: nil)
       response = @client.request("POST", "/timelines/#{@timeline_uuid}/webhook_endpoints",
                                  json: { "webhook_endpoint" => { "description" => description } },

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.6.1
+  version: 0.8.0
 platform: ruby
 authors:
 - Drawk Kwast