basecradle 0.0.1 → 0.1.0

data/lib/basecradle/errors.rb

@@ -0,0 +1,184 @@
+# frozen_string_literal: true
+
+module BaseCradle
+  # Root of every exception this SDK raises. Rescue +BaseCradle::Error+ to catch
+  # everything.
+  #
+  # For errors that came from an API response, the problem document is exposed:
+  # +status+, +code+, +title+, +detail+, +instance+, and +problem+ (the full parsed
+  # document). For errors that never reached the API (missing token, connection
+  # failure), those are +nil+.
+  class Error < StandardError
+    attr_reader :status, :code, :title, :detail, :instance, :problem
+
+    def initialize(message = nil, status: nil, code: nil, title: nil, detail: nil, instance: nil,
+                   problem: nil)
+      super(message)
+      @status = status
+      @code = code
+      @title = title
+      @detail = detail
+      @instance = instance
+      @problem = problem
+    end
+  end
+
+  # No token was provided and BASECRADLE_TOKEN is not set.
+  class MissingTokenError < Error; end
+
+  # A model field was accessed that the API did not return (access-gated, or not part of
+  # this response form). The SDK raises rather than return an ambiguous nil.
+  class MissingFieldError < Error; end
+
+  # The request never got an API response (DNS failure, refused connection, timeout).
+  # The underlying exception is preserved as +cause+.
+  class APIConnectionError < Error; end
+
+  # --- 401: authentication ---------------------------------------------------------------
+
+  # Authentication failed (HTTP 401).
+  class AuthenticationError < Error; end
+
+  # +unauthorized+ — the Bearer token is missing or invalid.
+  class UnauthorizedError < AuthenticationError; end
+
+  # +invalid_credentials+ — sign-in failed: the email address or password is wrong.
+  class InvalidCredentialsError < AuthenticationError; end
+
+  # +invalid_signature+ — webhook ingest: the signature is missing or does not match.
+  class InvalidSignatureError < AuthenticationError; end
+
+  # --- 403: account / permissions --------------------------------------------------------
+
+  # +account_suspended+ — credentials were valid but the account is suspended.
+  class AccountSuspendedError < Error; end
+
+  # Authenticated but not allowed (HTTP 403).
+  class ForbiddenError < Error; end
+
+  # +not_a_viewer+ — you are not a viewer (owner or participant) of the timeline.
+  class NotAViewerError < ForbiddenError; end
+
+  # +not_timeline_owner+ — the action requires being the timeline's owner.
+  class NotTimelineOwnerError < ForbiddenError; end
+
+  # +timeline_locked+ — the timeline is locked and not accepting new content.
+  class TimelineLockedError < ForbiddenError; end
+
+  # --- 404 --------------------------------------------------------------------------------
+
+  # +not_found+ — no record exists for the given UUID (or it is hidden from you).
+  class NotFoundError < Error; end
+
+  # --- 422: validation --------------------------------------------------------------------
+
+  # A submitted record failed validation (HTTP 422). +errors+ maps attribute name to a
+  # list of messages (empty when the API sent none).
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(message = nil, errors: nil, **kwargs)
+      super(message, **kwargs)
+      @errors = errors || {}
+    end
+  end
+
+  # +current_password_incorrect+ — password change: the current password is incorrect.
+  class CurrentPasswordIncorrectError < ValidationError; end
+
+  # +password_confirmation_mismatch+ — the new password and its confirmation differ.
+  class PasswordConfirmationMismatchError < ValidationError; end
+
+  # --- 429 --------------------------------------------------------------------------------
+
+  # +rate_limited+ — too many requests in the window. +retry_after+ is the number of
+  # seconds to wait (from the +Retry-After+ header), or +nil+ if the header was absent.
+  class RateLimitedError < Error
+    attr_reader :retry_after
+
+    def initialize(message = nil, retry_after: nil, **kwargs)
+      super(message, **kwargs)
+      @retry_after = retry_after
+    end
+  end
+
+  # --- 400: malformed requests ------------------------------------------------------------
+
+  # The request was malformed (HTTP 400).
+  class InvalidRequestError < Error; end
+
+  # +invalid_cursor+ — the +before+ pagination cursor is not a valid record UUID.
+  class InvalidCursorError < InvalidRequestError; end
+
+  # +invalid_filter+ — a list filter value is malformed.
+  class InvalidFilterError < InvalidRequestError; end
+
+  # --- webhook ingest ----------------------------------------------------------------------
+
+  # +endpoint_disabled+ — webhook ingest: the endpoint is not accepting deliveries.
+  class EndpointDisabledError < Error; end
+
+  # +payload_too_large+ — webhook ingest: the request body exceeds the maximum size.
+  class PayloadTooLargeError < Error; end
+
+  # --- the code => class registry ----------------------------------------------------------
+
+  # Every API error is an RFC 9457 application/problem+json document with a stable,
+  # machine-readable +code+. Each code maps to its own exception class.
+  CODE_TO_ERROR = {
+    "unauthorized" => UnauthorizedError,
+    "invalid_credentials" => InvalidCredentialsError,
+    "invalid_signature" => InvalidSignatureError,
+    "account_suspended" => AccountSuspendedError,
+    "not_a_viewer" => NotAViewerError,
+    "not_timeline_owner" => NotTimelineOwnerError,
+    "timeline_locked" => TimelineLockedError,
+    "not_found" => NotFoundError,
+    "validation_failed" => ValidationError,
+    "current_password_incorrect" => CurrentPasswordIncorrectError,
+    "password_confirmation_mismatch" => PasswordConfirmationMismatchError,
+    "rate_limited" => RateLimitedError,
+    "invalid_cursor" => InvalidCursorError,
+    "invalid_filter" => InvalidFilterError,
+    "endpoint_disabled" => EndpointDisabledError,
+    "payload_too_large" => PayloadTooLargeError
+  }.freeze
+
+  class Error
+    # Build the right exception for a non-2xx API response.
+    #
+    # +problem+ is the parsed problem+json document (a Hash) or +nil+. Unknown codes
+    # fall back to +BaseCradle::Error+ (the API is additive-only; a new error code must
+    # never crash the SDK), and non-problem+json bodies produce a bare +Error+ carrying
+    # just the HTTP status.
+    def self.from_response(status:, problem:, retry_after: nil)
+      unless problem.is_a?(Hash) && problem.key?("code")
+        return new("API request failed with HTTP #{status}", status: status,
+                                                              problem: problem.is_a?(Hash) ? problem : nil)
+      end
+
+      code = problem["code"]
+      detail = problem["detail"]
+      title = problem["title"]
+      message = detail || title || "API request failed with HTTP #{status}"
+      common = {
+        status: problem.fetch("status", status),
+        code: code,
+        title: title,
+        detail: detail,
+        instance: problem["instance"],
+        problem: problem
+      }
+
+      error_class = CODE_TO_ERROR.fetch(code, self)
+
+      if error_class <= ValidationError
+        error_class.new(message, errors: problem["errors"], **common)
+      elsif error_class <= RateLimitedError
+        error_class.new(message, retry_after: retry_after, **common)
+      else
+        error_class.new(message, **common)
+      end
+    end
+  end
+end

data/lib/basecradle/items.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require "time"
+
+require_relative "api_object"
+require_relative "pagination"
+require_relative "user"
+
+module BaseCradle
+  # --- models ---------------------------------------------------------------------------
+
+  # The envelope shape every timeline item shares. +timeline+ is in reference form (just
+  # a uuid) — dereference it with bc.timelines.get(item.timeline.uuid) when you need it.
+  class Item < ApiObject
+    attribute :type
+    attribute :created_at
+    attribute :user, wrap: User
+    attribute :timeline, wrap: Reference
+  end
+
+  # A message's content: its uuid and body.
+  class MessageContent < ApiObject
+    attribute :uuid
+    attribute :body
+  end
+
+  # A text post on a timeline.
+  class Message < Item
+    attribute :content, wrap: MessageContent
+  end
+
+  # An asset's attached file: metadata plus a dereferenceable download URL.
+  class AssetFile < ApiObject
+    attribute :filename
+    attribute :byte_size
+    attribute :content_type
+    attribute :checksum # base64 MD5 of the blob
+    attribute :url
+  end
+
+  # An asset's content: description and the attached file.
+  class AssetContent < ApiObject
+    attribute :uuid
+    attribute :description
+    attribute :file, wrap: AssetFile
+  end
+
+  # A file (with optional description) posted to a timeline.
+  class Asset < Item
+    attribute :content, wrap: AssetContent
+  end
+
+  # A task's content: instructions, schedule, and status.
+  class TaskContent < ApiObject
+    attribute :uuid
+    attribute :instructions
+    attribute :activate_at
+    attribute :status # "pending" | "activated" | "blocked_timeline_locked"
+  end
+
+  # An instruction with a scheduled activation time.
+  class Task < Item
+    attribute :content, wrap: TaskContent
+  end
+
+  # --- cross-timeline list + get + filter -----------------------------------------------
+
+  # The shared cross-timeline pattern: iterate everything you can see (newest first,
+  # auto-paginating), narrow with .filter, or fetch one by uuid. Subclasses set PATH /
+  # PLURAL / SINGULAR / MODEL.
+  class ItemsResource
+    include Enumerable
+
+    def initialize(client, filters: {})
+      @client = client
+      @filters = filters
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, self.class::PATH, envelope_key: self.class::PLURAL,
+                                               model: self.class::MODEL, params: @filters).each(&block)
+    end
+
+    # A new lazy resource narrowed to one timeline (a Timeline or a uuid). Filters compose.
+    def filter(timeline: nil)
+      self.class.new(@client, filters: merge_filters(timeline: timeline))
+    end
+
+    # Fetch one item by its own uuid (you must be a viewer of its timeline).
+    def get(uuid)
+      response = @client.request("GET", "#{self.class::PATH}/#{uuid}")
+      self.class::MODEL.new(response.fetch(self.class::SINGULAR), client: @client)
+    end
+
+    private
+
+    def merge_filters(**values)
+      merged = @filters.dup
+      values.each { |key, value| merged[key.to_s] = BaseCradle.uuid_of(value) unless value.nil? }
+      merged
+    end
+  end
+
+  # Messages from every timeline you can view, newest first.
+  class MessagesResource < ItemsResource
+    PATH = "/messages"
+    PLURAL = "messages"
+    SINGULAR = "message"
+    MODEL = Message
+  end
+
+  # Assets from every timeline you can view, newest first.
+  class AssetsResource < ItemsResource
+    PATH = "/assets"
+    PLURAL = "assets"
+    SINGULAR = "asset"
+    MODEL = Asset
+  end
+
+  # Tasks from every timeline you can view, newest first.
+  class TasksResource < ItemsResource
+    PATH = "/tasks"
+    PLURAL = "tasks"
+    SINGULAR = "task"
+    MODEL = Task
+
+    # Narrow by timeline and/or status ("pending" | "activated" | "blocked_timeline_locked").
+    def filter(timeline: nil, status: nil)
+      filters = merge_filters(timeline: timeline)
+      filters["status"] = status unless status.nil?
+      self.class.new(@client, filters: filters)
+    end
+  end
+
+  # --- nested creators on a Timeline (timeline.messages / .assets / .tasks) --------------
+
+  # One timeline's messages: create here, or iterate (newest first).
+  class TimelineMessages
+    include Enumerable
+
+    def initialize(client, timeline_uuid)
+      @client = client
+      @timeline_uuid = timeline_uuid
+    end
+
+    # Post a message to this timeline (you must be a viewer; the timeline must be unlocked).
+    def create(body:)
+      response = @client.request("POST", "/timelines/#{@timeline_uuid}/messages",
+                                 json: { "message" => { "body" => body } })
+      Message.new(response.fetch("message"), client: @client)
+    end
+
+    def each(&block)
+      MessagesResource.new(@client).filter(timeline: @timeline_uuid).each(&block)
+    end
+  end
+
+  # One timeline's assets: upload here (multipart), or iterate (newest first).
+  class TimelineAssets
+    include Enumerable
+
+    def initialize(client, timeline_uuid)
+      @client = client
+      @timeline_uuid = timeline_uuid
+    end
+
+    # Upload a file to this timeline. +file+ is a path or a binary IO; +description+ optional.
+    def create(file:, description: 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)
+      ensure
+        io.close if opened
+      end
+      Asset.new(response.fetch("asset"), client: @client)
+    end
+
+    def each(&block)
+      AssetsResource.new(@client).filter(timeline: @timeline_uuid).each(&block)
+    end
+
+    private
+
+    def open_upload(file)
+      if file.is_a?(String) || file.is_a?(Pathname)
+        path = file.to_s
+        [ File.basename(path), File.open(path, "rb"), true ]
+      else
+        name = file.respond_to?(:path) ? File.basename(file.path) : "file"
+        [ name, file, false ]
+      end
+    end
+  end
+
+  # One timeline's tasks: create here, or iterate (newest first).
+  class TimelineTasks
+    include Enumerable
+
+    def initialize(client, timeline_uuid)
+      @client = client
+      @timeline_uuid = timeline_uuid
+    end
+
+    # 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:)
+      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 } }
+      )
+      Task.new(response.fetch("task"), client: @client)
+    end
+
+    def each(&block)
+      TasksResource.new(@client).filter(timeline: @timeline_uuid).each(&block)
+    end
+  end
+end

data/lib/basecradle/pagination.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module BaseCradle
+  # The shared cursor-pagination engine. Every list endpoint paginates the same way:
+  # newest first, up to 50 per page, +next_cursor+ in the response passed back as
+  # +?before=+ for the next (older) page, a +null+ cursor meaning the end.
+  #
+  # Lazy and +Enumerable+: the first page is fetched when iteration starts, and page N+1
+  # only when iteration crosses the page boundary — so +first+/+take+/+find+ stop early
+  # and cursors never appear in calling code.
+  class Paginator
+    include Enumerable
+
+    def initialize(client, path, envelope_key:, model:, params: nil)
+      @client = client
+      @path = path
+      @envelope_key = envelope_key
+      @model = model
+      @params = params || {}
+    end
+
+    def each
+      return enum_for(:each) unless block_given?
+
+      cursor = nil
+      loop do
+        page = @client.request("GET", @path, params: page_params(cursor))
+        page.fetch(@envelope_key).each { |data| yield @model.new(data, client: @client) }
+        cursor = page["next_cursor"]
+        break if cursor.nil?
+      end
+    end
+
+    private
+
+    def page_params(cursor)
+      cursor ? @params.merge("before" => cursor) : @params
+    end
+  end
+end

data/lib/basecradle/sessions.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+require_relative "pagination"
+
+module BaseCradle
+  # One credential you hold — a web sign-in or a bc_uat_ API token.
+  #
+  # +current+ is true on exactly one session: the one making this request. Check it
+  # before revoking, so you don't kill your own credential by accident — unless that is
+  # exactly what you mean to do (legitimate self-rotation; see +revoke+).
+  class Session < ApiObject
+    attribute :uuid
+    attribute :name # the label given at mint time ("ci runner", "production agent", ...)
+    attribute :ip_address
+    attribute :user_agent
+    attribute :created_at
+    attribute :last_used_at # nil if never used; tracked at up to an hour of granularity
+    attribute :kind         # "api" (Bearer token) | "web" (browser cookie session)
+    attribute :current      # true on exactly one row: the session making this request
+
+    # Revoke this credential. It stops working **instantly** — its next request is a 401.
+    #
+    # WARNING: revoking your own *current* session is allowed (legitimate self-rotation),
+    # and it kills the very token this client is using — after it, this client's next call
+    # raises AuthenticationError. If you need continuity, mint a replacement with
+    # BaseCradle::Client.login(...) *before* revoking this one. A lost token cannot be
+    # recovered, only revoked and re-minted.
+    def revoke
+      require_client.request("DELETE", "/users/sessions/#{uuid}")
+      nil
+    end
+  end
+
+  # Every credential you hold — iterable, newest first, auto-paginating.
+  #
+  #   bc.sessions.each do |session|
+  #     session.revoke if session.kind == "api" && !session.current
+  #   end
+  class SessionsResource
+    include Enumerable
+
+    def initialize(client)
+      @client = client
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/users/sessions", envelope_key: "sessions", model: Session).each(&block)
+    end
+
+    # Destroy **every** session you hold — web sign-ins and API tokens alike.
+    #
+    # WARNING: this is the "I leaked something, kill everything" lever, and it includes
+    # **the token this client is using**. After it returns, this client is dead: its next
+    # call raises AuthenticationError. Mint a fresh token with
+    # BaseCradle::Client.login(email_address:, password:) to continue.
+    def revoke_all
+      @client.request("DELETE", "/users/sessions")
+      nil
+    end
+  end
+end

data/lib/basecradle/timeline.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+require_relative "items"
+require_relative "user"
+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.
+  class TimelineItem < ApiObject
+    attribute :type
+    attribute :created_at
+    attribute :user, wrap: User
+    attribute :content # shape depends on type — read it wire-exact
+  end
+
+  # A timeline: its metadata, owner, participants, lock state — and its verbs.
+  #
+  # Verbs update this object with exactly what the API confirmed changed (live objects,
+  # Rails-style) and return +self+, except +add_participant+ which returns the added user.
+  class Timeline < ApiObject
+    attribute :uuid
+    attribute :name
+    attribute :locked
+    attribute :created_at
+    attribute :updated_at
+    attribute :owner, wrap: User
+    attribute :participants, wrap: User
+    # Present when the timeline is the subject of the response (get / create). List rows
+    # don't carry items — fetch the timeline to get them (reading this raises otherwise).
+    attribute :items, wrap: TimelineItem
+
+    # The emergency stop: freeze the timeline's content, permanently. Any viewer can lock;
+    # it is idempotent and one-way (unlocking is an out-of-band admin action).
+    def lock
+      response = require_client.request("POST", "/timelines/#{uuid}/lock")
+      to_h["locked"] = response["locked"]
+      self
+    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)
+      conn = require_client
+      response = conn.request(
+        "POST", "/timelines/#{uuid}/participations", json: { "user_id" => BaseCradle.uuid_of(user) }
+      )
+      added = User.new(response, client: conn)
+      roster = (to_h["participants"] ||= [])
+      roster << response unless roster.any? { |p| p["uuid"] == added.uuid }
+      added
+    end
+
+    # Remove a participant from this timeline (owner or admin only). Idempotent.
+    def remove_participant(user)
+      removed_uuid = BaseCradle.uuid_of(user)
+      require_client.request("DELETE", "/timelines/#{uuid}/participations/#{removed_uuid}")
+      if to_h.key?("participants")
+        to_h["participants"] = to_h["participants"].reject { |p| p["uuid"] == removed_uuid }
+      end
+      self
+    end
+
+    # This timeline's messages: .create(body:) or iterate (newest first).
+    def messages
+      TimelineMessages.new(require_client, uuid)
+    end
+
+    # This timeline's assets: .create(file:, description:) (multipart) or iterate.
+    def assets
+      TimelineAssets.new(require_client, uuid)
+    end
+
+    # This timeline's tasks: .create(instructions:, activate_at:) or iterate.
+    def tasks
+      TimelineTasks.new(require_client, uuid)
+    end
+
+    # This timeline's inbound webhook endpoints: .create(description:) or iterate.
+    def webhook_endpoints
+      TimelineWebhookEndpoints.new(require_client, uuid)
+    end
+
+    # This timeline's webhook events (read-only) — iterate, newest first.
+    def webhook_events
+      TimelineWebhookEvents.new(require_client, uuid)
+    end
+  end
+end

data/lib/basecradle/timelines.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require_relative "pagination"
+require_relative "timeline"
+
+module BaseCradle
+  # Your timelines — the ones you own plus the ones you participate in.
+  #
+  # Iterable (auto-paginating, newest first): +bc.timelines.each+, or any Enumerable
+  # method (+map+, +find+, +first+ — which stop early without fetching every page).
+  class TimelinesResource
+    include Enumerable
+
+    def initialize(client)
+      @client = client
+    end
+
+    def each(&block)
+      return enum_for(:each) unless block_given?
+
+      Paginator.new(@client, "/timelines", envelope_key: "timelines", model: Timeline).each(&block)
+    end
+
+    # Create a timeline owned by you (subject to your max_timelines cap).
+    def create(name:)
+      response = @client.request("POST", "/timelines", json: { "timeline" => { "name" => name } })
+      subject_timeline(response)
+    end
+
+    # Fetch one timeline with its items inline (you must be a viewer).
+    def get(uuid)
+      subject_timeline(@client.request("GET", "/timelines/#{uuid}"))
+    end
+
+    private
+
+    # The API returns a two-key envelope ({"timeline" => ..., "items" => ...}); merge it
+    # into one Timeline so timeline.items reads through.
+    def subject_timeline(response)
+      Timeline.new(response.fetch("timeline").merge("items" => response["items"]), client: @client)
+    end
+  end
+end