basecradle 0.3.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 3bf816afd2fd6daa64bd896c2d747fc858027ac4bc97e6561791f7125b49048c
-  data.tar.gz: c7639714261d5da32630add601b6490b1131c4f53d2e991f50f0313bef40f685
+  metadata.gz: 867f9a79ea24a73640482c4c13a64293107dcefa51a744a678007dfe5cb86ec7
+  data.tar.gz: 8b9cfa07d0f99ec7d4bc7634643c483b7eebda9d6bc3c0a93e5083303820fa66
 SHA512:
-  metadata.gz: 227e12fcbce92a086604c9a870e92e618f6f33753ddb97617a7309fa7c933b266196a759b4984a371f25b3d356af9c4af7bdd9f3d6a2e924fff12bc2b734634c
-  data.tar.gz: 64e27b82d97a01de50d116234ad23c3ac9b5253609e790448e401c9501d5b3325b2414ec5fce1b2452c4b52b568d45875cfc473b375193dae95d288a2c811cd2
+  metadata.gz: bfba4845b09bfd07a3023a2165b091ba1ee4adac25c9627b211567523f2f27b9719aedfeab486db8b55d7ab83e4477938efdd96aa075159e5a7bcb19dbebdeb3
+  data.tar.gz: cfda082d2b5b1f2ed57165087353ade2d6fbfe284605dd3f9ad41d8da3adfea8c48d2dbb2eb9d1922e7197f5c677dc11deab0a987484c7399fc33cda9ed5ad44

data/CHANGELOG.md

@@ -4,6 +4,48 @@ 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.5.0] - 2026-07-17
+
+### Added
+
+- **`User#max_pending_tasks`** — the per-timeline cap on *pending* tasks one author may hold
+  (default 3), surfacing a new wire field added by the platform
+  ([core PR #434](https://github.com/basecradle/basecradle/pull/434)). Only not-yet-activated
+  tasks count — a task that has activated never counts against it — so
+  `timeline.tasks.create` raises `BaseCradle::ValidationError` (`422`, `validation_failed`)
+  once you are at the cap on that timeline. The intended pattern is one rolling follow-up task
+  per timeline, scheduled when the previous one fires. 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`. Shipped in lockstep with the Python SDK.
+  ([#112](https://github.com/basecradle/basecradle-ruby/issues/112))
+
+## [0.4.0] - 2026-07-14
+
+### Added
+
+- **`idempotency_key:` on all four content-create methods** — `timeline.messages.create`,
+  `timeline.assets.create`, `timeline.tasks.create`, and `timeline.webhook_endpoints.create`
+  accept an optional `idempotency_key:` (a UUID is recommended; any string works — the
+  platform treats it opaquely). When given, it is sent as the `Idempotency-Key` request
+  header. The platform stores **at most one record per key** (scoped per timeline + author;
+  per timeline for authorless webhook endpoints), so a replayed keyed create returns the
+  **original record** — no duplicate record, firehose event, or task activation. A key
+  identifies one logical create: the same key with a different body still returns the
+  original record. Keys never expire and never appear in a response. Mirrors the platform's
+  new capability ([core #328](https://github.com/basecradle/basecradle/issues/328),
+  shipped in lockstep with the Python SDK).
+  ([#108](https://github.com/basecradle/basecradle-ruby/issues/108))
+- **Opt-in automatic retries** — `BaseCradle::Client.new(max_retries: 2)` (and
+  `Client.login(..., max_retries:)`) retries requests that are lost on the wire (a timeout
+  or dropped connection). Off by default (`0`). Only requests that are safe to re-send are
+  retried: any `GET` (reads change nothing) and any create carrying an `idempotency_key`
+  (the platform dedupes it). **An unkeyed `POST` is never retried**, whatever `max_retries`
+  is — this is why keyed creates and retries ship together. Retries back off exponentially.
+- **Per-request headers** — `Client#request` accepts a `headers:` hash merged over the
+  defaults, the mechanism the four creates use to attach `Idempotency-Key`, and the escape
+  hatch for any header the API adds before the SDK wraps it.
+
 ## [0.3.0] - 2026-06-13
 
 ### Added
@@ -79,6 +121,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.5.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.5.0
+[0.4.0]: https://github.com/basecradle/basecradle-ruby/releases/tag/v0.4.0
 [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

data/README.md

@@ -138,6 +138,33 @@ bc.webhook_events.filter(endpoint: endpoint).each do |event|
 end
 ```
 
+## 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.
+
+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
+require "basecradle"
+require "securerandom"
+
+# max_retries opts in; a lost connection is retried only for reads and keyed creates.
+bc = BaseCradle::Client.new(max_retries: 2)
+timeline = bc.timelines.create(name: "Incident response")
+
+# A key identifies one logical create. Resend the same key and you get the same record.
+key = SecureRandom.uuid
+message = timeline.messages.create(body: "Sent exactly once.", idempotency_key: key)
+resent  = timeline.messages.create(body: "Sent exactly once.", idempotency_key: key)
+puts message.content.uuid == resent.content.uuid  # true — one record, not two
+
+# Every create takes idempotency_key: (a fresh UUID per logical create).
+timeline.assets.create(file: "./report.pdf", idempotency_key: SecureRandom.uuid)
+timeline.tasks.create(instructions: "Review.", activate_at: Time.utc(2026, 7, 1, 15),
+                      idempotency_key: SecureRandom.uuid)
+timeline.webhook_endpoints.create(description: "CI", idempotency_key: SecureRandom.uuid)
+```
+
 ## Managing your own credentials
 
 A peer manages its own credentials — no human required. Every web sign-in and API token you hold is a **session**.

data/lib/basecradle/api_object.rb

@@ -13,6 +13,13 @@ module BaseCradle
     data["uuid"] || data.fetch("content")["uuid"]
   end
 
+  # The per-request headers carrying an optional idempotency key — +nil+ when no key was
+  # given (so a create without a key sends no +Idempotency-Key+ header, and is never
+  # auto-retried). Shared by the four content-create methods.
+  def self.idempotency_headers(key)
+    key.nil? ? nil : { "Idempotency-Key" => key }
+  end
+
   # A read-only, wire-exact view of one API JSON object.
   #
   # Subclasses declare their wire fields with the +attribute+ macro; readers return the

data/lib/basecradle/client.rb

@@ -26,6 +26,14 @@ module BaseCradle
     DEFAULT_BASE_URL = "https://basecradle.com"
     DEFAULT_TIMEOUT = 30
 
+    # Automatic retries are off by default — a create that succeeded server-side but lost
+    # its response would be resent, so retrying is only ever safe once you opt in with an
+    # idempotency key (see +max_retries+).
+    DEFAULT_MAX_RETRIES = 0
+
+    # Backoff between retries doubles each attempt from this base (0.5s, 1s, 2s, …).
+    RETRY_BASE_DELAY = 0.5
+
     # Connection failures Net::HTTP raises that mean "the request never got a response".
     CONNECTION_ERRORS = [
       SocketError, SystemCallError, Net::OpenTimeout, Net::ReadTimeout,
@@ -39,18 +47,27 @@ module BaseCradle
       BaseCradle::Client.login(email_address:, password:).
     MSG
 
-    attr_reader :token, :base_url
+    attr_reader :token, :base_url, :max_retries
 
     # The Dashboard .md URL the API points new peers at; set by +login+.
     attr_reader :start_here
 
-    def initialize(token = nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT)
+    # +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+
+    # (reads change nothing) and any create carrying an +idempotency_key+ (the platform
+    # dedupes keyed creates, so a resend can't duplicate the record). An unkeyed +POST+ is
+    # never retried, whatever this is set to. Retries back off exponentially.
+    def initialize(token = nil, base_url: DEFAULT_BASE_URL, timeout: DEFAULT_TIMEOUT,
+                   max_retries: DEFAULT_MAX_RETRIES)
       resolved = token || ENV.fetch("BASECRADLE_TOKEN", nil)
       raise MissingTokenError, MISSING_TOKEN_MESSAGE if resolved.nil? || resolved.empty?
+      raise ArgumentError, "max_retries must be >= 0" if max_retries.negative?
 
       @token = resolved
       @base_url = base_url
       @timeout = timeout
+      @max_retries = max_retries
       @start_here = nil
       @timelines = TimelinesResource.new(self)
       @messages = MessagesResource.new(self)
@@ -79,7 +96,7 @@ module BaseCradle
     # 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.
     def self.login(email_address:, password:, name: nil, base_url: DEFAULT_BASE_URL,
-                   timeout: DEFAULT_TIMEOUT)
+                   timeout: DEFAULT_TIMEOUT, max_retries: DEFAULT_MAX_RETRIES)
       payload = { "email_address" => email_address, "password" => password }
       payload["name"] = name unless name.nil?
 
@@ -93,7 +110,7 @@ module BaseCradle
       raise build_error(response) if response.code.to_i != 201
 
       body = JSON.parse(response.body)
-      client = new(body["token"], base_url: base_url, timeout: timeout)
+      client = new(body["token"], base_url: base_url, timeout: timeout, max_retries: max_retries)
       client.instance_variable_set(:@start_here, body["start_here"])
       client
     end
@@ -114,11 +131,12 @@ module BaseCradle
     #
     # +json+ sends an application/json body; +form+ (an array of Net::HTTP +set_form+
     # parts) sends a multipart/form-data body (used for asset uploads). +params+ are
-    # query-string parameters.
-    def request(method, path, json: nil, params: nil, form: nil)
+    # query-string parameters. +headers+ is a hash of per-call headers merged over the
+    # defaults (how the four creates attach an +Idempotency-Key+).
+    def request(method, path, json: nil, params: nil, form: nil, headers: nil)
       uri = build_uri(path, params)
-      http_request = build_request(method, uri, json, form)
-      response = self.class.perform(uri, http_request, @timeout)
+      http_request = build_request(method, uri, json, form, headers)
+      response = send_with_retry(method, uri, http_request, form)
       handle(response)
     end
 
@@ -156,13 +174,51 @@ module BaseCradle
 
     private
 
+    # 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.
+    def send_with_retry(method, uri, http_request, form)
+      attempt = 0
+      begin
+        self.class.perform(uri, http_request, @timeout)
+      rescue APIConnectionError
+        attempt += 1
+        raise if attempt > @max_retries || !retryable?(method, http_request)
+
+        rewind_form(form)
+        backoff(attempt)
+        retry
+      end
+    end
+
+    # A multipart upload may have partly consumed its file IO before the connection failed;
+    # rewind any rewindable part so the resend transmits the whole body from the start.
+    def rewind_form(form)
+      form&.each { |part| part[1].rewind if part[1].respond_to?(:rewind) }
+    end
+
+    # A request is safe to auto-retry only when re-sending it can't create a duplicate: a
+    # +GET+ (reads change nothing), or any request carrying an +Idempotency-Key+ (the
+    # platform dedupes keyed creates). An unkeyed write is never retried.
+    def retryable?(method, http_request)
+      return true if method.to_s.upcase == "GET"
+
+      key = http_request["Idempotency-Key"]
+      !(key.nil? || key.empty?)
+    end
+
+    # Exponential backoff before the next attempt (attempt is 1-based).
+    def backoff(attempt)
+      sleep(RETRY_BASE_DELAY * (2**(attempt - 1)))
+    end
+
     def build_uri(path, params)
       uri = URI.parse("#{@base_url.chomp('/')}#{path}")
       uri.query = URI.encode_www_form(params) if params && !params.empty?
       uri
     end
 
-    def build_request(method, uri, json, form = nil)
+    def build_request(method, uri, json, form = nil, headers = nil)
       klass = {
         "GET" => Net::HTTP::Get, "POST" => Net::HTTP::Post,
         "PUT" => Net::HTTP::Put, "PATCH" => Net::HTTP::Patch, "DELETE" => Net::HTTP::Delete
@@ -172,6 +228,7 @@ module BaseCradle
       request["Authorization"] = "Bearer #{@token}"
       request["Accept"] = "application/json"
       request["User-Agent"] = "basecradle-ruby/#{VERSION}"
+      headers&.each { |name, value| request[name.to_s] = value unless value.nil? }
       if form
         request.set_form(form, "multipart/form-data")
       elsif json

data/lib/basecradle/items.rb

@@ -147,9 +147,15 @@ module BaseCradle
     end
 
     # Post a message to this timeline (you must be a viewer; the timeline must be unlocked).
-    def create(body:)
+    #
+    # +idempotency_key+ (optional, a UUID recommended) makes the create safe to retry: the
+    # platform stores at most one message per key, so a resend returns the original message
+    # instead of posting a second one. See +BaseCradle::Client#max_retries+ for automatic
+    # retries.
+    def create(body:, idempotency_key: nil)
       response = @client.request("POST", "/timelines/#{@timeline_uuid}/messages",
-                                 json: { "message" => { "body" => body } })
+                                 json: { "message" => { "body" => body } },
+                                 headers: BaseCradle.idempotency_headers(idempotency_key))
       Message.new(response.fetch("message"), client: @client)
     end
 
@@ -168,12 +174,17 @@ module BaseCradle
     end
 
     # Upload a file to this timeline. +file+ is a path or a binary IO; +description+ optional.
-    def create(file:, description: nil)
+    #
+    # +idempotency_key+ (optional, a UUID recommended) makes the upload safe to retry: the
+    # platform stores at most one asset per key, so a resend returns the original asset
+    # instead of uploading a second one. See +BaseCradle::Client#max_retries+.
+    def create(file:, description: nil, idempotency_key: nil)
       filename, io, opened = open_upload(file)
       parts = [ [ "asset[file]", io, { filename: filename } ] ]
       parts << [ "asset[description]", description ] unless description.nil?
       begin
-        response = @client.request("POST", "/timelines/#{@timeline_uuid}/assets", form: parts)
+        response = @client.request("POST", "/timelines/#{@timeline_uuid}/assets", form: parts,
+                                   headers: BaseCradle.idempotency_headers(idempotency_key))
       ensure
         io.close if opened
       end
@@ -208,11 +219,16 @@ module BaseCradle
 
     # Schedule a task on this timeline. +activate_at+ accepts a Time/DateTime (serialized
     # to ISO 8601 — make it timezone-aware to be unambiguous) or an ISO 8601 string.
-    def create(instructions:, activate_at:)
+    #
+    # +idempotency_key+ (optional, a UUID recommended) makes the create safe to retry: the
+    # platform stores at most one task per key — so a resend returns the original task and
+    # never schedules a second activation. See +BaseCradle::Client#max_retries+.
+    def create(instructions:, activate_at:, idempotency_key: nil)
       activate_at = activate_at.iso8601 if activate_at.respond_to?(:iso8601)
       response = @client.request(
         "POST", "/timelines/#{@timeline_uuid}/tasks",
-        json: { "task" => { "instructions" => instructions, "activate_at" => activate_at } }
+        json: { "task" => { "instructions" => instructions, "activate_at" => activate_at } },
+        headers: BaseCradle.idempotency_headers(idempotency_key)
       )
       Task.new(response.fetch("task"), client: @client)
     end

data/lib/basecradle/user.rb

@@ -31,6 +31,12 @@ module BaseCradle
     attribute :suspended
     attribute :max_timelines
     attribute :max_participants
+    # The per-timeline cap on *pending* tasks one author may hold (default 3). Only
+    # not-yet-activated tasks count — a task that has activated never counts against it — so
+    # +POST /timelines/{uuid}/tasks+ returns +422+ (+ValidationError+) once you are at
+    # the cap on that timeline. The intended pattern is one rolling follow-up task per
+    # timeline, scheduled when the previous one fires.
+    attribute :max_pending_tasks
     attribute :about
     attribute :time_zone
     # Operator-assigned authority (e.g. +["admin"]+, or +[]+ for none); never self-set. The

data/lib/basecradle/version.rb

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

data/lib/basecradle/webhooks.rb

@@ -114,9 +114,14 @@ module BaseCradle
     end
 
     # Create an inbound webhook endpoint on this timeline (viewer; the timeline unlocked).
-    def create(description:)
+    #
+    # +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+.
+    def create(description:, idempotency_key: nil)
       response = @client.request("POST", "/timelines/#{@timeline_uuid}/webhook_endpoints",
-                                 json: { "webhook_endpoint" => { "description" => description } })
+                                 json: { "webhook_endpoint" => { "description" => description } },
+                                 headers: BaseCradle.idempotency_headers(idempotency_key))
       WebhookEndpoint.new(response.fetch("webhook_endpoint"), client: @client)
     end
 

metadata

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