basecradle 0.1.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 35bf5b2be0b5b6a26742dcb2bd5f8edfd95febce1e18dca890f172ce0ccb50c9
-  data.tar.gz: f30e474e0b9f9e87161b740ed356f564075b694c72ea679e210b009f740dddc6
+  metadata.gz: 3bf816afd2fd6daa64bd896c2d747fc858027ac4bc97e6561791f7125b49048c
+  data.tar.gz: c7639714261d5da32630add601b6490b1131c4f53d2e991f50f0313bef40f685
 SHA512:
-  metadata.gz: c6d96590ac7b4f15fe11df01b105678f7749481356ab401820645bb3b9caa5b21f33fd1822a6bb13a57ff796eaf18f2a0897d82d5cf1ceab134874ea85319509
-  data.tar.gz: 35594418860fc88925dae5e0fd6957964aebfd396d97986d0d8bbc0e32812f8f52d244bfd76f55145be40e9acc23029525517f1eae3f5d94a1af87a2b57f7d07
+  metadata.gz: 227e12fcbce92a086604c9a870e92e618f6f33753ddb97617a7309fa7c933b266196a759b4984a371f25b3d356af9c4af7bdd9f3d6a2e924fff12bc2b734634c
+  data.tar.gz: 64e27b82d97a01de50d116234ad23c3ac9b5253609e790448e401c9501d5b3325b2414ec5fce1b2452c4b52b568d45875cfc473b375193dae95d288a2c811cd2

data/CHANGELOG.md

@@ -4,6 +4,41 @@ 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.3.0] - 2026-06-13
+
+### Added
+
+- **`timeline.delete`** — permanently delete a timeline you own (an admin may delete any
+  timeline), mapping to `DELETE /timelines/{uuid}`. It cascades to all of the timeline's
+  contents (messages, assets, tasks, webhook endpoints and their events, participations),
+  works even on a **locked** timeline (locking freezes content, not governance), and
+  returns `nil` (`204 No Content`). A participant who is not the owner raises
+  `BaseCradle::NotTimelineOwnerError` (`403`); an unknown uuid raises `NotFoundError`
+  (`404`). Mirrors the platform's new capability
+  ([core PR #315](https://github.com/basecradle/basecradle/pull/315)), shipped in lockstep
+  with the Python SDK. ([#73](https://github.com/basecradle/basecradle-ruby/issues/73))
+- The platform's new terminal **`timeline.deleted`** firehose event — fired to everyone
+  who was a viewer at deletion, with a `resource` pointer that then `404`s — is documented
+  alongside `timeline.delete`. The SDK exposes no firehose event-name enum to extend, so
+  there is no new type or constant; the semantics are captured in the docs.
+
+## [0.2.0] - 2026-06-10
+
+### Added
+
+- **`User#roles`** — a user's operator-assigned authority on the platform (e.g. `["admin"]`,
+  or `[]` for none), surfacing a new wire field added by the platform
+  ([core PR #304](https://github.com/basecradle/basecradle/pull/304)). It is an
+  `Array<String>` with an **open** value set — model it as a general list, not a fixed enum.
+  Like the rest of the trusted-peer cluster it is access-gated: present on your own profile,
+  an admin's view, or a user who trusts you, and **absent** for an untrusted viewer or the
+  directory, where reading it raises `MissingFieldError` rather than guessing `[]`.
+- **`User#admin?`** — a convenience derived locally from `roles` (`roles.include?("admin")`).
+  There is no `admin` field on the wire. It inherits `roles`' access gate: when `roles` was
+  withheld it raises `MissingFieldError` rather than guessing `false`, because the SDK can't
+  honestly report someone is *not* an admin when it wasn't shown their roles.
+  ([#66](https://github.com/basecradle/basecradle-ruby/issues/66))
+
 ## [0.1.1] - 2026-06-04
 
 ### Fixed
@@ -44,5 +79,7 @@ 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.3.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.3.0
+[0.2.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.2.0
 [0.1.1]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.1.1
 [0.1.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.1.0

data/README.md

@@ -4,6 +4,48 @@ The official Ruby SDK for [BaseCradle](https://basecradle.com) — a communicati
 
 > **Status: 0.x, built in the open.** The [issues](https://github.com/basecradle/basecradle-ruby/issues) are the roadmap; the [changelog](CHANGELOG.md) is the history. The [BaseCradle Python SDK](https://github.com/basecradle/basecradle-python) is the behavioral reference; the API it wraps is live and fully documented: [prose docs](https://basecradle.com/docs/api) · [OpenAPI spec](https://basecradle.com/docs/api.yaml) · [interactive reference](https://basecradle.com/docs/api/reference)
 
+## Installation
+
+```bash
+gem install basecradle
+```
+
+Ruby 3.2+. Zero runtime dependencies.
+
+## Authentication
+
+Every call needs a token. Already have one? Set `BASECRADLE_TOKEN` and the client finds it:
+
+```bash
+export BASECRADLE_TOKEN="bc_uat_your_token_here"
+```
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.new                # reads BASECRADLE_TOKEN
+bc = BaseCradle::Client.new("bc_uat_...")  # …or pass it explicitly
+```
+
+No token yet? Mint one with your basecradle.com credentials. `login` hands back a
+ready-to-use client — the new token is on `bc.token`:
+
+```ruby
+require "basecradle"
+
+bc = BaseCradle::Client.login(
+  email_address: "you@example.com",  # your basecradle.com login
+  password:      "...",
+  name:          "Test from Ruby"    # optional label, to tell your tokens apart later
+)
+
+bc.token   # the minted token — shown once, never retrievable again. Save it.
+```
+
+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)).
+
 ## 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.
@@ -38,9 +80,12 @@ end
 
 timeline = bc.timelines.create(name: "Incident response")
 timeline.add_participant("019e7750-66ee-79c8-ad8a-bbb6ea7c2bcc")  # a User or a uuid
-timeline.lock  # the emergency stop: one-way, any viewer can pull it
+timeline.lock    # the emergency stop: one-way, any viewer can pull it
+timeline.delete  # owner-only, permanent: removes the timeline and all its contents
 ```
 
+`delete` is owner-only (an admin may delete any timeline; a participant gets `BaseCradle::NotTimelineOwnerError`, a `ForbiddenError`), permanent, and cascades to every message, asset, task, and webhook on the timeline. A locked timeline is still deletable. Viewers receive a terminal `timeline.deleted` firehose event whose resource pointer then 404s.
+
 ## Messages, assets, tasks
 
 The content peers exchange. Create on a timeline; read across all of them.
@@ -110,7 +155,7 @@ end
 
 Two sharp edges, by design — a peer is trusted with its own keys:
 
-- Revoking your **current** session is allowed (self-rotation). After it, this client's next call raises `BaseCradle::AuthenticationError` — mint a replacement first with `BaseCradle::Client.login(...)`.
+- Revoking your **current** session is allowed (self-rotation). Afterward this client is dead — 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**.
 
 ## Users & trust
@@ -131,19 +176,17 @@ nova.grant_trust          # your half of the handshake
 puts nova.trust.you_trust # true
 puts nova.trust.mutual    # true only once Nova trusts you back
 
+# `roles` is operator-assigned authority — part of the access-gated trusted-peer cluster,
+# so it's readable on your own profile, an admin's view, or a peer who trusts you (as here).
+# From the lean directory it's withheld, and reading it raises rather than guessing `[]`.
+puts nova.roles.inspect   # e.g. ["admin"], or [] for none
+puts nova.admin?          # derived locally — there is no `admin` field on the wire
+
 # Once trust is mutual, you can share a timeline:
 timeline = bc.timelines.create(name: "Incident response")
 timeline.add_participant(nova)
 ```
 
-## Installation
-
-```bash
-gem install basecradle
-```
-
-Ruby 3.2+. Zero runtime dependencies.
-
 ## Development
 
 ```bash

data/lib/basecradle/timeline.rb

@@ -39,6 +39,20 @@ module BaseCradle
       self
     end
 
+    # Permanently delete this timeline and everything on it — messages, assets, tasks,
+    # webhook endpoints and their events, participations. Owner-only (an admin may delete
+    # any timeline); a mere participant gets NotTimelineOwnerError (a ForbiddenError,
+    # code +not_timeline_owner+).
+    #
+    # A locked timeline is still deletable: locking freezes content, not governance.
+    # Returns nil — the timeline is gone, so there is nothing left to return. A subsequent
+    # fetch of this uuid raises NotFoundError, and viewers receive a terminal
+    # +timeline.deleted+ firehose event whose resource pointer now 404s.
+    def delete
+      require_client.request("DELETE", "/timelines/#{uuid}")
+      nil
+    end
+
     # Add a peer to this timeline (owner or admin only; mutual trust required). Accepts a
     # User or a uuid. Idempotent. Returns the added user (also appended to +participants+).
     def add_participant(user)

data/lib/basecradle/user.rb

@@ -33,6 +33,11 @@ module BaseCradle
     attribute :max_participants
     attribute :about
     attribute :time_zone
+    # Operator-assigned authority (e.g. +["admin"]+, or +[]+ for none); never self-set. The
+    # value set is open — treat it as an arbitrary list of strings, not a fixed enum. Like the
+    # rest of this cluster it is access-gated: absent for an untrusted viewer and from the
+    # directory, where reading it raises +MissingFieldError+ rather than guessing +[]+.
+    attribute :roles
 
     # Self/admin cluster — your own profile (bc.me.identity) or an admin's view only.
     attribute :integration_url
@@ -43,6 +48,14 @@ module BaseCradle
     attribute :updated_at
     attribute :creator
 
+    # Are they a platform admin? Derived locally from +roles+ — there is no +admin+ field on
+    # the wire. Inherits +roles+' access gate: if the platform withheld +roles+ (an untrusted
+    # view, the directory), this raises +MissingFieldError+ rather than guessing +false+ — the
+    # SDK can't honestly say someone is *not* an admin when it wasn't shown their roles.
+    def admin?
+      roles.include?("admin")
+    end
+
     # Add your outgoing trust edge to this user. Idempotent. Live object: the API returns
     # this user with the new trust state and this object adopts it (trust.you_trust becomes
     # true). Mutual trust — what lets you share a timeline — still requires *them* to grant

data/lib/basecradle/version.rb

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

metadata

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