Class: BaseCradle::Timeline

Inherits:
ApiObject show all
Defined in:
lib/basecradle/timeline.rb

Overview

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.

Instance Method Summary collapse

Methods inherited from ApiObject

#==, #[], attribute, #hash, #initialize, #inspect, #to_h

Constructor Details

This class inherits a constructor from BaseCradle::ApiObject

Instance Method Details

#add_participant(user) ⇒ Object

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).



58
59
60
61
62
63
64
65
66
67
 
# File 'lib/basecradle/timeline.rb', line 58

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

#assets ⇒ Object

This timeline’s assets: .create(file:, description:) (multipart) or iterate.



85
86
87
 
# File 'lib/basecradle/timeline.rb', line 85

def assets
  TimelineAssets.new(require_client, uuid)
end

#delete ⇒ Object

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.



51
52
53
54
 
# File 'lib/basecradle/timeline.rb', line 51

def delete
  require_client.request("DELETE", "/timelines/#{uuid}")
  nil
end

#lock ⇒ Object

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).



36
37
38
39
40
 
# File 'lib/basecradle/timeline.rb', line 36

def lock
  response = require_client.request("POST", "/timelines/#{uuid}/lock")
  to_h["locked"] = response["locked"]
  self
end

#messages ⇒ Object

This timeline’s messages: .create(body:) or iterate (newest first).



80
81
82
 
# File 'lib/basecradle/timeline.rb', line 80

def messages
  TimelineMessages.new(require_client, uuid)
end

#remove_participant(user) ⇒ Object

Remove a participant from this timeline (owner or admin only). Idempotent.



70
71
72
73
74
75
76
77
 
# File 'lib/basecradle/timeline.rb', line 70

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

#tasks ⇒ Object

This timeline’s tasks: .create(instructions:, activate_at:) or iterate.



90
91
92
 
# File 'lib/basecradle/timeline.rb', line 90

def tasks
  TimelineTasks.new(require_client, uuid)
end

#webhook_endpoints ⇒ Object

This timeline’s inbound webhook endpoints: .create(description:) or iterate.



95
96
97
 
# File 'lib/basecradle/timeline.rb', line 95

def webhook_endpoints
  TimelineWebhookEndpoints.new(require_client, uuid)
end

#webhook_events ⇒ Object

This timeline’s webhook events (read-only) — iterate, newest first.



100
101
102
 
# File 'lib/basecradle/timeline.rb', line 100

def webhook_events
  TimelineWebhookEvents.new(require_client, uuid)
end