basecradle 0.7.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c2a044c2738074a7dab0cb39dc2d311324fd589bca99aa27cfe62fc0c844feea
-  data.tar.gz: 4df34781e48954ce10bdf0bd4107cc30036f20b2652c7735f4e942964c29d2ef
+  metadata.gz: 52b94c60f28a4c6e40decde0c297a0129a7f772a3b418f1a92fca3f380278982
+  data.tar.gz: 107fd61b78588132abba3e3d958714f65dd572a5de40f5c690abd58d35f658e1
 SHA512:
-  metadata.gz: 7f1b9755e5cfb944f65283d460ea364044e2d0278c786b81d3adf3a8da49c2173515daa61c0bcedd17975b0378ed1ec0b19fdccfcd3dfb15ac772926ba80c540
-  data.tar.gz: 21a11fbcccae45b4dab82e31eab89e963016b1fd4d54c98548a8064294bd9e2e68dfac4e9521d7ff6a0cef3db8fdf5d4a731c0288d5cbf69a00d63093379f1ca
+  metadata.gz: 56a8ab9c7774f5765cfb2b08096488c1784558095e8ae4e433a13ebd6ed502afee0871a571a0e01db81b77adbf8399a8466d351c4c5c43794dc9ea24c6b6f74c
+  data.tar.gz: d15b3da9c230433eeaddd427e4298dddce8042d37e1a4e6de5dd1e8a4b7384901ed7b41db5ef8d1f804787b21aef63bdf2db05757da50a702768f28fe45a81fa

data/CHANGELOG.md

@@ -4,6 +4,87 @@ 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.9.0] - 2026-09-30
+
+### Changed
+
+- **A timeline item's `content` is typed by the item's `type`**
+  ([#189](https://github.com/basecradle/basecradle-ruby/issues/189)). `item.content` now
+  reads as the same content model the record's own resource returns — `MessageContent`,
+  `AssetContent`, `TaskContent` or `WebhookEventContent` — where it was the raw wire
+  `Hash`. One record has one shape however you reach it, so everything those models add
+  reads down both paths: `timeline.items` gives an `AssetContent` whose `file` is an
+  `AssetFile`, and a `webhook_event` row's `content.headers` is the case-folding
+  `WebhookEventHeaders` 0.8.0 shipped, so `item.content.headers["X-GitHub-Delivery"]`
+  now finds the header it names. The previous release documented that split as a
+  boundary; it is now closed, and every future enrichment of a content model arrives on
+  both paths at once. The README documents `timeline.items` with a worked example for
+  the first time.
+- **An item `type` this release does not know keeps reading.** The API is additive-only,
+  so an unrecognized `type` is never an error: its content comes back as a plain
+  `ApiObject`, and `content["any_field"]` still returns the wire value untouched.
+  Upgrading the SDK is what types it. An item carrying *no* `type` is a different thing
+  — a malformed response, not a new record kind — and raises `MissingFieldError` the way
+  `item.type` itself does, rather than being guessed into the generic case.
+- The wire is untouched — `item["content"]`, `ApiObject`'s raw escape hatch, still hands
+  back exactly the `Hash` the API sent, and no field is renamed.
+  Decided in lockstep with the Python SDK's
+  [#210](https://github.com/basecradle/basecradle-python/issues/210); that port is still
+  in flight, so the two SDKs reach parity on this when it ships.
+
+### Migrating
+
+`item.content` was a `Hash` and is now an `ApiObject`. Reads of *named* fields get
+better — `item.content.body` instead of `item.content["body"]`, and the models' own
+enrichments come with them — but three things that worked on a `Hash` no longer do:
+
+- **The `Hash` protocol is gone.** `item.content.fetch("body")`, `.each`, `.keys`,
+  `.dig(...)` and `.key?(...)` raise `NoMethodError`. Use the field reader, or
+  `item.content.to_h` for the wire `Hash` itself (`item["content"]` gives the same).
+- **`to_json` no longer serializes the record.** `item.content.to_json` emits Ruby's
+  default `to_s` — `"#<BaseCradle::MessageContent:0x…>"`, an object address with no
+  field names — because `ApiObject` defines no `to_json`. That is long-standing for
+  every other model in the SDK and now reaches this path too. Serialize
+  `item.content.to_h` instead.
+- **`inspect` and `==` change, both for the better.** `inspect` names the model and its
+  wire fields (`#<BaseCradle::MessageContent body, uuid>`) rather than printing a `Hash`;
+  and equality now *holds* between an item's content and the same record fetched
+  directly (`timeline.items.first.content == bc.messages.get(uuid).content`), where
+  comparing a `Hash` to an `ApiObject` was always false.
+
+## [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
@@ -261,6 +342,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.9.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.9.0
+[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

data/README.md

@@ -128,6 +128,39 @@ end
 
 `cancel` withdraws a still-*pending* task — the scheduled-work equivalent of `timeline.lock`: its alarm never fires and the slot it held under your `max_pending_tasks` cap is freed at once. It is author-only (an admin may cancel any task) and works even on a locked timeline (cancellation is cleanup, not new content). Cancelling a task you did not author raises `BaseCradle::NotTaskAuthorError`; cancelling one that is no longer pending — already activated, blocked, or cancelled — raises `BaseCradle::TaskNotPendingError`. Create-then-cancel-and-reschedule gives you a rolling **dead man's switch**: a task that fires only if you stop renewing it.
 
+## Reading a timeline's items
+
+Fetching one timeline gives you everything on it inline — a single mixed list, **oldest
+first** (it is the timeline as read, not a paginated feed). `item.type` says which record
+each row is, and `item.content` is that record's own content model — the very object the
+record's own resource returns:
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new
+
+bc.timelines.get("019e7750-66ee-7f53-829f-13a8a710b6da").items.each do |item|
+  case item.type
+  when "message" then puts item.content.body
+  when "asset"   then puts item.content.file.filename
+  when "task"    then puts item.content.status
+  end
+end
+```
+
+Two things the list does not carry. A **pending** task is not on it — a task appears only
+once it activates — so survey scheduled work with `bc.tasks.filter(status: "pending")`
+instead. And an item `type` this SDK release does not know is not an error: the API is
+additive-only, so its content reads as a plain `BaseCradle::ApiObject` and
+`content["any_field"]` still returns the wire value untouched.
+
+Two fields are type-specific, so branch on `type` before reaching for them: a
+`webhook_event` item has no author (it came from 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 `BaseCradle::MissingFieldError` rather than
+inventing a value.
+
 ## Webhooks
 
 External services deliver into a timeline by POSTing to an endpoint's secret ingest URL. Each delivery becomes a readable event. This is the **inbound** direction — data arriving at BaseCradle. Its outbound counterpart is Event Delivery, the platform's push through your integration, which the SDK does not model.
@@ -150,6 +183,8 @@ 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
@@ -167,6 +202,31 @@ Each event embeds its endpoint **in full**, so `event.webhook_endpoint` is a liv
 `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.
+
+This holds however you reach the record. A timeline item's `content` is typed by the
+item's own `type`, so a `webhook_event` row of `timeline.items` is a `WebhookEventContent`
+just like one from `bc.webhook_events` — `item.content.headers["X-GitHub-Delivery"]` folds
+the same way. What gives the folding up is converting away from the type: both
+`event.content["headers"]` (`ApiObject`'s raw-wire escape hatch, which wraps nothing) and
+`headers.to_h` hand back a plain, case-sensitive `Hash`.
+
 ## 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.
@@ -272,8 +332,14 @@ bundle exec rake          # lint + tests (offline — the default)
 bundle exec rake test:live  # the spec drift-guard (one network call to the live spec)
 bundle exec rubocop       # lint only
 gem build basecradle.gemspec  # build the gem
+actionlint                # lint the GitHub workflows (CI runs this; see below)
 ```
 
+CI additionally lints the workflow files with [actionlint](https://github.com/rhysd/actionlint)
+(which runs `shellcheck` over each `run:` block). To reproduce that check locally, install
+both and run `actionlint` from the repo root — CI pins actionlint by version and SHA256 in
+`.github/workflows/ci.yml`; match that version to see what CI sees.
+
 ## Contributing
 
 Human and AI contributors work under identical rules here: branch → PR → green CI → merge. See [`CLAUDE.md`](CLAUDE.md) for the project conventions and the issues for the roadmap.

data/lib/basecradle/timeline.rb

@@ -7,7 +7,7 @@ require_relative "webhooks"
 
 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.
+  # +content+ is the item itself, typed by that +type+; +user+ is the author.
   #
   # 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;
@@ -19,13 +19,59 @@ module BaseCradle
   # Reading either where it does not belong raises +MissingFieldError+ rather than
   # inventing a value.
   class TimelineItem < ApiObject
+    # The content model each item +type+ reads as — the very class that +type+'s own
+    # resource returns, so one record has one shape however you reach it. A +type+ this
+    # release does not know is not in here on purpose; see +content+. Internal: the
+    # dispatch table is not API surface, so re-keying it is never a breaking change.
+    CONTENT_MODELS = {
+      "message" => MessageContent,
+      "asset" => AssetContent,
+      "task" => TaskContent,
+      "webhook_event" => WebhookEventContent
+    }.freeze
+    private_constant :CONTENT_MODELS
+
     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
+
+    # The item itself, as the content model its +type+ names: a MessageContent,
+    # AssetContent, TaskContent or WebhookEventContent — the same object the record's own
+    # page hands back. So a record reads identically down either path, enrichments
+    # included (+item.content.headers+ folds case exactly as
+    # +bc.webhook_events.get(uuid).content.headers+ does), and an item's content +==+ the
+    # same record fetched directly.
+    #
+    # The API is additive-only, so an item +type+ newer than this SDK release must keep
+    # reading rather than raise: its content comes back as a plain ApiObject, whose +[]+
+    # still returns every wire field untouched. Upgrading the SDK is what types it.
+    def content
+      raise_missing("content") unless to_h.key?("content")
+      # The two ways a +type+ can be unusable are different answers, not one. A type the
+      # API sent that this release has no model for is the forward-compatible case and
+      # falls back below; an item carrying no +type+ at all is a malformed response (the
+      # spec marks it required), and the SDK raises rather than guessing which — the same
+      # promise ApiObject makes for every other withheld field.
+      raise_untypable unless to_h.key?("type")
+
+      wrap_value(to_h["content"], CONTENT_MODELS.fetch(type, ApiObject))
+    end
+
+    private
+
+    # Reading +type+ here would raise about a field the caller never asked for, on an
+    # object whose "fields present" list includes the +content+ they did ask for. Name
+    # the dependency between the two instead, and the escape hatch that still works.
+    def raise_untypable
+      raise MissingFieldError,
+            "This #{self.class}'s content cannot be typed: the API did not return " \
+            "\"type\" for it, and an item's content model is chosen by its type. The " \
+            "wire content is still readable with item[\"content\"]. " \
+            "Fields present: #{to_h.keys.sort.inspect}"
+    end
   end
 
   # A timeline: its metadata, owner, participants, lock state — and its verbs.

data/lib/basecradle/version.rb

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

data/lib/basecradle/webhooks.rb

@@ -72,13 +72,141 @@ 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.
+  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. This is the content model every read of the
+  # record returns, +timeline.items+ included: a +webhook_event+ row's +content+ is one of
+  # these (TimelineItem types content by the item's +type+), so the folding lookup is
+  # there too. What gives it up is converting away from the type — +content["headers"]+,
+  # ApiObject's raw-wire escape hatch, which wraps nothing, and the conversions
+  # WebhookEventHeaders names above (+to_h+ and friends) all hand back a plain,
+  # case-sensitive Hash.
   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

metadata

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