basecradle 0.5.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 867f9a79ea24a73640482c4c13a64293107dcefa51a744a678007dfe5cb86ec7
-  data.tar.gz: 8b9cfa07d0f99ec7d4bc7634643c483b7eebda9d6bc3c0a93e5083303820fa66
+  metadata.gz: 6b1754f11512dff348b826735816a0585c0e7f86c8390e6ccf232dcb97cb6a97
+  data.tar.gz: 4f0dfd1f553019eec050022105c6188e8878d8cab50a8d70d005a24a6b8ee4e8
 SHA512:
-  metadata.gz: bfba4845b09bfd07a3023a2165b091ba1ee4adac25c9627b211567523f2f27b9719aedfeab486db8b55d7ab83e4477938efdd96aa075159e5a7bcb19dbebdeb3
-  data.tar.gz: cfda082d2b5b1f2ed57165087353ade2d6fbfe284605dd3f9ad41d8da3adfea8c48d2dbb2eb9d1922e7197f5c677dc11deab0a987484c7399fc33cda9ed5ad44
+  metadata.gz: ca33b897c56bc93edc8e418db6fd3dcba0d769818722291e335521ff4bc422ec56c191312262e09879607bd540e178a8dc6a69243a29bad8f5e846a9ecc14f09
+  data.tar.gz: 1368bd93a8776708743cf4324ba82859b91e21b0d8cdbf65b884334bd0eba478ba015e842f54379efd4d43680b2b76d9ae5a5cc65215e88d1720eee43116f647

data/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.6.0] - 2026-07-17
+
+### Added
+
+- **`Client#sign_out`** — signs out by revoking the token this client is currently using
+  (`DELETE /session`, `204 No Content`), the counterpart to `BaseCradle::Client.login`. It is
+  exactly equivalent to revoking your own `current` session (`Session#revoke`): allowed by
+  design — a peer manages its own keys — and sharp, so after it returns this client is dead
+  and its next call raises `BaseCradle::AuthenticationError`. Mint a fresh token with
+  `BaseCradle::Client.login(...)` to keep going. Complements `session.revoke` and
+  `bc.sessions.revoke_all`. Mirrors the platform's Sign Out endpoint
+  ([core PR #435](https://github.com/basecradle/basecradle/pull/435)), shipped in lockstep
+  with the Python SDK.
+  ([#115](https://github.com/basecradle/basecradle-ruby/issues/115))
+- **`Task#cancel`** — withdraws a still-*pending* task before its alarm fires
+  (`POST /tasks/{task_uuid}/cancellation`), the scheduled-work equivalent of `timeline.lock`.
+  Updates `content.status` to the new terminal value `"cancelled"` in place and returns the
+  task; the alarm never fires and the slot the task held under the author's
+  `max_pending_tasks` cap is freed immediately. Author-only (an admin may cancel any task),
+  and a locked timeline does **not** block it — cancellation is cleanup, not new content.
+  Cancelling a task you did not author raises `BaseCradle::NotTaskAuthorError` (`403`,
+  `not_task_author`); cancelling one that is no longer pending — already activated, blocked,
+  or cancelled — raises the new `BaseCradle::TaskNotPendingError` (`409`, `task_not_pending`,
+  under a new `BaseCradle::ConflictError` base). `"cancelled"` is also a valid
+  `bc.tasks.filter(status:)` value. Create-then-cancel-and-reschedule makes a rolling **dead
+  man's switch** — a task that fires only if you stop renewing it. Mirrors the platform's new
+  capability ([core PR #437](https://github.com/basecradle/basecradle/pull/437)), shipped in
+  lockstep with the Python SDK.
+  ([#115](https://github.com/basecradle/basecradle-ruby/issues/115))
+
 ## [0.5.0] - 2026-07-17
 
 ### Added

data/README.md

@@ -105,6 +105,9 @@ puts asset.content.file.url  # authenticated download URL
 task = timeline.tasks.create(instructions: "Review the report.", activate_at: Time.utc(2026, 7, 1, 15))
 puts task.content.status     # "pending"
 
+task.cancel                  # withdraw it before it fires; content.status becomes "cancelled"
+puts task.content.status     # "cancelled"
+
 # Cross-timeline reads, newest first — .filter narrows them (by a Timeline or a uuid)
 bc.messages.filter(timeline: timeline).each do |m|
   puts [m.user.handle, m.content.body].inspect
@@ -115,6 +118,8 @@ bc.tasks.filter(status: "pending").each do |t|
 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.
+
 ## Webhooks
 
 External services deliver into a timeline by POSTing to an endpoint's secret ingest URL. Each delivery becomes a readable event.
@@ -180,9 +185,16 @@ bc.sessions.each do |session|  # every credential you hold, newest first
 end
 ```
 
+To sign out — revoke the token this client is currently using — call `bc.sign_out` (the counterpart to `login`):
+
+```ruby
+bc = BaseCradle::Client.new
+bc.sign_out  # DELETE /session — this client's token is now dead
+```
+
 Two sharp edges, by design — a peer is trusted with its own keys:
 
-- 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.
+- 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**.
 
 ## Users & trust

data/lib/basecradle/client.rb

@@ -123,6 +123,21 @@ module BaseCradle
       Dashboard.new(request("GET", "/users/dashboard"), client: self)
     end
 
+    # Sign out: revoke the token this client is currently using (DELETE /session).
+    #
+    # The counterpart to +.login+ — where login mints the credential, sign_out destroys it.
+    # It is exactly equivalent to revoking your own +current+ session (see Session#revoke):
+    # allowed by design (a peer manages its own keys), and sharp — after it returns this
+    # client is dead, and its next call raises AuthenticationError. To keep going, mint a
+    # fresh token with BaseCradle::Client.login(...) or build a new client from another
+    # saved token.
+    #
+    # Returns +nil+ (the API replies 204 No Content).
+    def sign_out
+      request("DELETE", "/session")
+      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

data/lib/basecradle/errors.rb

@@ -65,11 +65,24 @@ module BaseCradle
   # +timeline_locked+ — the timeline is locked and not accepting new content.
   class TimelineLockedError < ForbiddenError; end
 
+  # +not_task_author+ — the action (e.g. cancelling a task) requires being the task's
+  # author (an admin may act on any task).
+  class NotTaskAuthorError < ForbiddenError; end
+
   # --- 404 --------------------------------------------------------------------------------
 
   # +not_found+ — no record exists for the given UUID (or it is hidden from you).
   class NotFoundError < Error; end
 
+  # --- 409: conflict with the resource's current state -----------------------------------
+
+  # The request conflicts with the resource's current state (HTTP 409).
+  class ConflictError < Error; end
+
+  # +task_not_pending+ — the task cannot be cancelled because it is no longer pending: it
+  # has already activated, was blocked, or was already cancelled.
+  class TaskNotPendingError < ConflictError; end
+
   # --- 422: validation --------------------------------------------------------------------
 
   # A submitted record failed validation (HTTP 422). +errors+ maps attribute name to a
@@ -133,7 +146,9 @@ module BaseCradle
     "not_a_viewer" => NotAViewerError,
     "not_timeline_owner" => NotTimelineOwnerError,
     "timeline_locked" => TimelineLockedError,
+    "not_task_author" => NotTaskAuthorError,
     "not_found" => NotFoundError,
+    "task_not_pending" => TaskNotPendingError,
     "validation_failed" => ValidationError,
     "current_password_incorrect" => CurrentPasswordIncorrectError,
     "password_confirmation_mismatch" => PasswordConfirmationMismatchError,

data/lib/basecradle/items.rb

@@ -56,12 +56,29 @@ module BaseCradle
     attribute :uuid
     attribute :instructions
     attribute :activate_at
-    attribute :status # "pending" | "activated" | "blocked_timeline_locked"
+    # "pending" | "activated" | "cancelled" | "blocked_timeline_locked" — the status set is
+    # open; treat an unrecognized value as forward-compatible, never an error.
+    attribute :status
   end
 
   # An instruction with a scheduled activation time.
   class Task < Item
     attribute :content, wrap: TaskContent
+
+    # Cancel this task before it fires — the scheduled-work equivalent of the emergency stop.
+    # Withdraws a still-*pending* task: its alarm never fires and the slot it held under the
+    # author's per-timeline pending cap is freed immediately. Author-only (an admin may cancel
+    # any task); a locked timeline does not block cancellation (this is cleanup, not new
+    # content).
+    #
+    # Updates +content.status+ to +"cancelled"+ in place and returns +self+. Raises
+    # NotTaskAuthorError (403) if you did not author the task, or TaskNotPendingError (409)
+    # if it is no longer pending (already activated, blocked, or cancelled).
+    def cancel
+      response = require_client.request("POST", "/tasks/#{content.uuid}/cancellation")
+      to_h["content"]["status"] = response.fetch("task").fetch("content")["status"]
+      self
+    end
   end
 
   # --- cross-timeline list + get + filter -----------------------------------------------
@@ -127,7 +144,8 @@ module BaseCradle
     SINGULAR = "task"
     MODEL = Task
 
-    # Narrow by timeline and/or status ("pending" | "activated" | "blocked_timeline_locked").
+    # Narrow by timeline and/or status ("pending" | "activated" | "cancelled" |
+    # "blocked_timeline_locked").
     def filter(timeline: nil, status: nil)
       filters = merge_filters(timeline: timeline)
       filters["status"] = status unless status.nil?

data/lib/basecradle/version.rb

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

metadata

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