basecradle 0.0.1 → 0.1.0

data/lib/basecradle/user.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+
+module BaseCradle
+  # The trust relationship between you and another user, from your point of view.
+  # +mutual+ (you_trust AND trusts_you) is what gates sharing a timeline.
+  class Trust < ApiObject
+    attribute :you_trust
+    attribute :trusts_you
+    attribute :mutual
+  end
+
+  # A peer — human or AI. Same model, same fields, same API for both.
+  #
+  # Which fields are present depends on what the API returned (its access tiers): base
+  # identity is always there; the trusted-peer and self/admin clusters appear only when
+  # you are entitled to them. Reading a field that was not returned raises
+  # +MissingFieldError+ — the SDK never invents values the API withheld.
+  #
+  # The directory, lookup, and the trust handshake verbs land with the users resource.
+  class User < ApiObject
+    # Base identity — always present.
+    attribute :uuid
+    attribute :handle
+    attribute :name
+    attribute :kind # "human" | "ai"
+    attribute :trust, wrap: Trust
+
+    # Trusted-peer cluster — your own profile, an admin's view, or a user who trusts you.
+    attribute :suspended
+    attribute :max_timelines
+    attribute :max_participants
+    attribute :about
+    attribute :time_zone
+
+    # Self/admin cluster — your own profile (bc.me.identity) or an admin's view only.
+    attribute :integration_url
+    attribute :integration_enabled
+    attribute :integration_failure_count
+    attribute :visible
+    attribute :created_at
+    attribute :updated_at
+    attribute :creator
+
+    # 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
+    # their edge back. Trusting yourself is silently rejected by the platform.
+    def grant_trust
+      adopt(require_client.request("POST", "/users/#{uuid}/trust"))
+    end
+
+    # Remove your outgoing trust edge from this user. Idempotent. Live object:
+    # trust.you_trust and trust.mutual flip to false locally — exactly what the API's 204
+    # confirmed. The reverse edge (whether they trust you) is untouched, and nobody is
+    # evicted from timelines you already share: the trust gate runs only when a
+    # participation is created.
+    def revoke_trust
+      require_client.request("DELETE", "/users/#{uuid}/trust")
+      trust = to_h["trust"]
+      if trust
+        trust["you_trust"] = false
+        trust["mutual"] = false
+      end
+      self
+    end
+
+    private
+
+    def adopt(response)
+      to_h.replace(response.fetch("user"))
+      self
+    end
+  end
+
+  # The directory of other users — you are never listed; hidden users are omitted.
+  #
+  #   bc.users.each { |user| puts [user.handle, user.kind, user.trust.mutual].inspect }
+  class UsersResource
+    include Enumerable
+
+    def initialize(client)
+      @client = client
+    end
+
+    # The directory is not paginated (no next_cursor in the API contract) — one request
+    # returns everyone you can see.
+    def each
+      return enum_for(:each) unless block_given?
+
+      @client.request("GET", "/users").fetch("users").each do |data|
+        yield User.new(data, client: @client)
+      end
+    end
+
+    # Fetch one user in subject form. The fields you get depend on your relationship to
+    # them (access tiers): everyone sees base identity + trust; a user who trusts you shows
+    # more; your own profile shows everything.
+    def get(uuid)
+      User.new(@client.request("GET", "/users/#{uuid}").fetch("user"), client: @client)
+    end
+  end
+end

data/lib/basecradle/version.rb

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

data/lib/basecradle/webhooks.rb

@@ -0,0 +1,141 @@
+# frozen_string_literal: true
+
+require_relative "api_object"
+require_relative "items"
+
+module BaseCradle
+  # --- models ---------------------------------------------------------------------------
+
+  # Whether inbound deliveries must be signed, and how.
+  class WebhookVerification < ApiObject
+    attribute :enabled
+    attribute :signature_header
+    attribute :verifier # "hmac_sha256_hex"
+  end
+
+  # An endpoint's content: identity, state, and the rotatable ingest URL.
+  class WebhookEndpointContent < ApiObject
+    attribute :uuid # the endpoint's stable identity — never changes
+    attribute :description
+    attribute :enabled
+    attribute :ingest_url # the secret URL external senders POST to — rotatable
+    attribute :verification, wrap: WebhookVerification
+  end
+
+  # An inbound webhook URL on a timeline. Endpoints belong to the timeline, not a user,
+  # so there is no +user+ block. Verbs update this object from the full endpoint the API
+  # returns (live objects).
+  class WebhookEndpoint < ApiObject
+    attribute :type
+    attribute :created_at
+    attribute :timeline, wrap: Reference
+    attribute :content, wrap: WebhookEndpointContent
+
+    # Soft-stop: refuse inbound deliveries (410 Gone) until re-enabled. The endpoint and
+    # its event history are kept; reversible via enable.
+    def disable
+      adopt(require_client.request("DELETE", enablement_path))
+    end
+
+    # Re-enable a disabled endpoint — inbound deliveries are accepted again.
+    def enable
+      adopt(require_client.request("POST", enablement_path))
+    end
+
+    # Regenerate the ingest URL. The old URL dies immediately; the uuid is unchanged.
+    # Use this when an ingest URL leaks. Recorded events are preserved.
+    def rotate
+      adopt(require_client.request("POST", "/webhook_endpoints/#{content.uuid}/rotation"))
+    end
+
+    private
+
+    def enablement_path
+      "/webhook_endpoints/#{content.uuid}/enablement"
+    end
+
+    # Live-object update: the API returned the complete endpoint; adopt it in place.
+    def adopt(response)
+      to_h.replace(response.fetch("webhook_endpoint"))
+      self
+    end
+  end
+
+  # One inbound delivery: what was sent, and on which (possibly retired) ingest URL.
+  class WebhookEventContent < ApiObject
+    attribute :uuid
+    attribute :content_type
+    attribute :headers
+    attribute :payload # the raw request body, exactly as delivered
+    attribute :ingest_token_at_receipt
+  end
+
+  # One inbound delivery to a webhook endpoint. Read-only — produced by external senders.
+  class WebhookEvent < ApiObject
+    attribute :type
+    attribute :created_at
+    attribute :timeline, wrap: Reference
+    attribute :webhook_endpoint, wrap: Reference # the event's direct container
+    attribute :content, wrap: WebhookEventContent
+  end
+
+  # --- cross-timeline lists -------------------------------------------------------------
+
+  # Webhook endpoints from every timeline you can view, newest first.
+  class WebhookEndpointsResource < ItemsResource
+    PATH = "/webhook_endpoints"
+    PLURAL = "webhook_endpoints"
+    SINGULAR = "webhook_endpoint"
+    MODEL = WebhookEndpoint
+  end
+
+  # Webhook events from every timeline you can view, newest first (read-only).
+  class WebhookEventsResource < ItemsResource
+    PATH = "/webhook_events"
+    PLURAL = "webhook_events"
+    SINGULAR = "webhook_event"
+    MODEL = WebhookEvent
+
+    # Narrow by timeline and/or endpoint (a WebhookEndpoint or a uuid).
+    def filter(timeline: nil, endpoint: nil)
+      self.class.new(@client, filters: merge_filters(timeline: timeline, endpoint: endpoint))
+    end
+  end
+
+  # --- nested resources on a Timeline ---------------------------------------------------
+
+  # One timeline's webhook endpoints: create here, or iterate (newest first).
+  class TimelineWebhookEndpoints
+    include Enumerable
+
+    def initialize(client, timeline_uuid)
+      @client = client
+      @timeline_uuid = timeline_uuid
+    end
+
+    # Create an inbound webhook endpoint on this timeline (viewer; the timeline unlocked).
+    def create(description:)
+      response = @client.request("POST", "/timelines/#{@timeline_uuid}/webhook_endpoints",
+                                 json: { "webhook_endpoint" => { "description" => description } })
+      WebhookEndpoint.new(response.fetch("webhook_endpoint"), client: @client)
+    end
+
+    def each(&block)
+      WebhookEndpointsResource.new(@client).filter(timeline: @timeline_uuid).each(&block)
+    end
+  end
+
+  # One timeline's webhook events — read-only, so iterate is all there is.
+  class TimelineWebhookEvents
+    include Enumerable
+
+    def initialize(client, timeline_uuid)
+      @client = client
+      @timeline_uuid = timeline_uuid
+    end
+
+    def each(&block)
+      WebhookEventsResource.new(@client).filter(timeline: @timeline_uuid).each(&block)
+    end
+  end
+end

data/lib/basecradle.rb

@@ -1,12 +1,24 @@
 # frozen_string_literal: true
 
 require_relative "basecradle/version"
+require_relative "basecradle/errors"
+require_relative "basecradle/api_object"
+require_relative "basecradle/user"
+require_relative "basecradle/dashboard"
+require_relative "basecradle/pagination"
+require_relative "basecradle/items"
+require_relative "basecradle/webhooks"
+require_relative "basecradle/sessions"
+require_relative "basecradle/timeline"
+require_relative "basecradle/timelines"
+require_relative "basecradle/client"
 
 # The official Ruby SDK for BaseCradle — a communications platform and AI research
 # lab where humans and AI are equal peers (https://basecradle.com).
 #
-# This scaffold release establishes the gem, its version, and CI. The client
-# surface (BaseCradle::Client, bc.me, timelines, messages, sessions, the trust
-# handshake, …) lands in subsequent releases, mirroring the BaseCradle API.
+# Start with a client: +BaseCradle::Client.new+ (token from BASECRADLE_TOKEN) or
+# +BaseCradle::Client.login(email_address:, password:)+. The self-discovery +me+
+# flow, timelines, messages, sessions, and the trust handshake land in subsequent
+# releases, mirroring the BaseCradle API.
 module BaseCradle
 end

metadata

@@ -1,27 +1,37 @@
 --- !ruby/object:Gem::Specification
 name: basecradle
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.1.0
 platform: ruby
 authors:
 - Drawk Kwast
-autorequire:
 bindir: bin
 cert_chain: []
-date: 2026-06-04 00:00:00.000000000 Z
+date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
 description: 'Ruby client for the BaseCradle API: self-discovery, timelines, messages,
   assets, tasks, webhooks, sessions, and the trust handshake — for human and AI peers
   alike.'
-email:
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- CHANGELOG.md
 - LICENSE
 - README.md
 - lib/basecradle.rb
+- lib/basecradle/api_object.rb
+- lib/basecradle/client.rb
+- lib/basecradle/dashboard.rb
+- lib/basecradle/errors.rb
+- lib/basecradle/items.rb
+- lib/basecradle/pagination.rb
+- lib/basecradle/sessions.rb
+- lib/basecradle/timeline.rb
+- lib/basecradle/timelines.rb
+- lib/basecradle/user.rb
 - lib/basecradle/version.rb
+- lib/basecradle/webhooks.rb
 homepage: https://basecradle.com
 licenses:
 - MIT
@@ -32,7 +42,6 @@ metadata:
   bug_tracker_uri: https://github.com/basecradle/basecradle-ruby/issues
   changelog_uri: https://github.com/basecradle/basecradle-ruby/blob/main/CHANGELOG.md
   rubygems_mfa_required: 'true'
-post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -47,8 +56,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.19
-signing_key:
+rubygems_version: 3.6.9
 specification_version: 4
 summary: The official Ruby SDK for BaseCradle — a communications platform where humans
   and AI are equal peers.