basecradle 0.8.0 → 0.10.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9766c4ae3f22a8dcb26bb88bac8931e8257dd429ea8ba4a56af26d4eda9fb8ae
-  data.tar.gz: 1504a5d791f9a5874cbbfea13abff10a64f17c9f6b5f557898e90c19a03182cb
+  metadata.gz: 3acdf9b8dad4d29a40926030c480cc415b96ffff03c56a121838b4fdb42cd638
+  data.tar.gz: 2b88488a27cae407aa366cce9899da840b7ea1e74db86d21c511f0f2b1ac47d7
 SHA512:
-  metadata.gz: 5c0677055d1b17309e17a5303ac381c5364f4083403626279236d1f214f3d40a203126d71b27b658ebd808642565523ea27690feedbd4ee9d595d440f9b77b72
-  data.tar.gz: acb01b5cdfc88eb6d62006b221d2f84c876151dad8169ce3020bed6d73acc6cb7a6c2777de0efaea183b2c4fab5c02f1ab437b222b80adb5d13a0c44ffe60a7e
+  metadata.gz: 7f753c98128c1935e0503dd1963917ac1918e171401b4a39f6c1b650cd716213f02c52b1dd538a54bb201de0ede89af19e7ab2ec9abfa79d2eba68d71faa5f57
+  data.tar.gz: 31772a4161d2e3563a835ffbd2c9ae5a2d9e285a157ca2772be3213037297b168f8e89b67e8290a7897a77a009add74b9769bf5e623ac5256ec19f26eece04d9

data/CHANGELOG.md

@@ -4,6 +4,108 @@ 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).
 
+One deliberate departure from that format: this changelog keeps **no `Unreleased`
+section**. The newest heading is always the version `lib/basecradle/version.rb` builds —
+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.10.0] - 2026-09-30
+
+### Fixed
+
+- **A model serializes as the record it stands for**
+  ([#191](https://github.com/basecradle/basecradle-ruby/issues/191)). `ApiObject` defined
+  no `to_json`, so serializing *any* model — `bc.me`, a `Timeline`, a `Message`, any
+  content object — fell through to Ruby's default and emitted a heap address:
+  `"#<BaseCradle::MessageContent:0x000072be94b09…>"`. Silently, with no field names and a
+  different value every run. `model.to_json` and `JSON.generate(model)` now emit the
+  record, and so does a model nested in an array or a hash. What `to_h` holds is exactly
+  what goes out: nothing renamed, nothing dropped, and a field newer than this SDK
+  release serialized like any other.
+  `WebhookEventHeaders` is unchanged — it subclasses `Hash`, so it already serialized as
+  the delivery's headers.
+  Long-standing; 0.9.0's typing of `timeline.items` content only widened which read path
+  reached it. **0.9.0's Migrating note on `to_json` is superseded by this release.**
+
+### Added
+
+- **`as_json`**, ActiveSupport's serialization hook, returning the same wire `Hash` as
+  `to_h`. It is what reaches a model nested inside a structure Rails renders
+  (`render json: { user: bc.me }`); a bare `render json: model` calls `to_json` directly
+  and never reaches it. Two things to know, neither of which a Rails habit expects:
+  - **It returns the same `Hash` as `to_h`, not a copy** — read-only by the same
+    convention, where every ActiveSupport `as_json` builds a fresh one. So
+    `model.as_json.merge!(extra)` rewrites the model's wire record, and for a wrapped
+    child its parent's too. Use `model.to_h.dup` (shallow) if you need to touch it.
+  - **Options are accepted and ignored, `only:` and `except:` included** — a model is a
+    read of one record, not a presenter. `as_json(except: ["ingest_url"])` returns the
+    whole record, silently, and it *disagrees* with `to_json`: with ActiveSupport loaded
+    `model.to_json(except: [...])` does redact, because the option reaches `Hash#to_json`.
+    Do not route redaction through either — build the subset with
+    `model.to_h.except("ingest_url")`.
+
+  `to_json` forwards its argument to `Hash#to_json` rather than swallowing it, so
+  `JSON.pretty_generate` pretty-prints; what an unknown option does is the host app's
+  `json` version's business (3.x raises, the 2.x older Rubies ship ignores it).
+
+  `to_s` is untouched, so interpolating a model (`"#{model}"`, `puts model`) still shows
+  the default object form. `inspect` names the model and its fields; `to_json` / `to_h`
+  give the record.
+
+  Minor rather than patch: the `to_json` output is a fix, but `as_json` is new public
+  surface and 0.9.0 documented the old behavior as expected — semver takes the higher.
+
+## [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.
+  > ⚠️ **Superseded in [0.10.0](#0100---2026-09-30)**, which gives `ApiObject` a
+  > `to_json`. `item.content.to_json` emits the record; the `to_h` workaround above is
+  > no longer needed. Left as written for the historical record.
+- **`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
@@ -294,6 +396,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.10.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.10.0
+[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

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.
@@ -187,11 +220,12 @@ fallback-less `fetch` raise `KeyError` naming the headers that did arrive, while
 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.
+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
 
@@ -290,6 +324,41 @@ timeline = bc.timelines.create(name: "Incident response")
 timeline.add_participant(nova)
 ```
 
+## Reading models, and serializing them
+
+Every model is a read-only, wire-exact view of one API JSON object. Field readers mirror
+the wire names; `model[key]` is the raw escape hatch for a field newer than your SDK
+release; `model.to_h` is the wire `Hash` itself.
+
+Models serialize as the record they stand for — what `to_h` holds is what goes out, so
+logging or re-emitting one gives you the wire record rather than an object address:
+
+```ruby
+require "basecradle"
+require "json"
+
+bc = BaseCradle::Client.new
+message = bc.messages.first
+
+puts message.content.to_json                  # {"uuid":"019e...","body":"Hello from a peer."}
+puts JSON.generate([message.content])         # nested in an array
+puts({ latest: message.content }.to_json)     # nested in a hash
+```
+
+`as_json` is ActiveSupport's hook and returns the same wire `Hash`, so a model nested in
+something Rails renders comes out right too. Three caveats worth knowing:
+
+- **`as_json` returns the same `Hash` as `to_h`, not a copy** — read-only by the same
+  convention. Mutating it rewrites the model's record. Use `model.to_h.dup` (shallow).
+- **Options are accepted and ignored, `only:` and `except:` included.** A model is a read
+  of one record, not a presenter, so `as_json(except: ["ingest_url"])` returns the whole
+  record, silently — and it *disagrees* with `to_json`, which under ActiveSupport does
+  redact, because the option reaches `Hash#to_json`. Do not route redaction through
+  either: build the subset with `model.to_h.except("ingest_url")`.
+- **`to_json` forwards its argument** to `Hash#to_json`, so `JSON.pretty_generate`
+  pretty-prints. What an unknown option does is your `json` version's business — 3.x
+  raises, the 2.x older Rubies ship ignores it.
+
 ## Development
 
 ```bash
@@ -298,8 +367,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/api_object.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "json"
+
 require_relative "errors"
 
 module BaseCradle
@@ -61,6 +63,46 @@ module BaseCradle
       @data
     end
 
+    # The wire record, for a serializer — ActiveSupport's hook, and what reaches a model
+    # nested inside a structure Rails renders (<tt>render json: { user: bc.me }</tt>).
+    # A bare <tt>render json: model</tt> calls +to_json+ instead and never comes here.
+    #
+    # Returns +to_h+: the wire keys, nothing renamed, nothing dropped, and a field newer
+    # than this release carried like any other. (It is the record *as this object holds
+    # it* — for a Timeline fetched whole, that is the API's two-key envelope merged into
+    # one object, so it carries +items+ alongside the timeline's own fields.)
+    #
+    # Two traps, because neither is what a Rails habit expects:
+    #
+    # - **It is the same Hash +to_h+ returns, not a copy** — read-only by the same
+    #   convention, where every ActiveSupport +as_json+ builds a fresh one. So
+    #   <tt>model.as_json.merge!(extra)</tt> rewrites the model's wire record, and for a
+    #   wrapped child its parent's too (a child wraps the parent's own nested Hash).
+    #   +to_h.dup+ if you need to touch it; note that is shallow.
+    # - **Options are accepted and ignored, +only:+ and +except:+ included** — a model is
+    #   a read of one record, not a presenter. +as_json(except: ["ingest_url"])+ returns
+    #   the whole record, *silently*. Worse, it disagrees with +to_json+: with
+    #   ActiveSupport loaded <tt>model.to_json(except: [...])</tt> *does* redact, because
+    #   the option reaches +Hash#to_json+. Do not rely on either — build the subset
+    #   yourself with <tt>model.to_h.except("ingest_url")</tt>.
+    def as_json(*)
+      to_h
+    end
+
+    # The wire record as JSON. Without this a model fell through to Ruby's default and
+    # emitted a heap address — silently, with no field names and a different value every
+    # run. +JSON.generate+ and +Array#to_json+ / +Hash#to_json+ call this, so a model
+    # nested in either serializes correctly too.
+    #
+    # The argument is forwarded to +Hash#to_json+ rather than swallowed, so
+    # +JSON.pretty_generate+ pretty-prints — and what an unknown option does is the host
+    # app's json version's business, not this SDK's: json 3.x raises on an unknown
+    # keyword, the json 2.x that older Rubies ship ignores it, and ActiveSupport acts on
+    # +only:+ / +except:+. See +as_json+ above: do not route redaction through either.
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
     def ==(other)
       other.instance_of?(self.class) && other.to_h == @data
     end

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.8.0"
+  VERSION = "0.10.0"
 end

data/lib/basecradle/webhooks.rb

@@ -196,11 +196,13 @@ module BaseCradle
   # 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.
+  # 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

metadata

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