Class: X::Space

Inherits:
Resource show all
Extended by:
BatchFinders
Defined in:
x-objects/lib/x/objects/space.rb

Overview

A live audio space

The space endpoints take only app-only authentication, so a client that signs with OAuth 1.0a reads spaces with a copy that authenticates as the app, while the spaces and posts it reads hold the client, so that they act as the user.

Constant Summary collapse

FIELDS =

Every public space field

A minor release may add to it the fields the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of fields of its own.

%w[created_at ended_at id is_ticketed lang participant_count scheduled_start started_at state
subscriber_count title updated_at].freeze
EXPANSIONS =

Every expansion available on space endpoints

A minor release may add to it the expansions the API adds, so that a lookup asks for them too; see Resource#hydrated? for what that means for a resource looked up with a list of expansions of its own.

%w[creator_id host_ids invited_user_ids speaker_ids topic_ids].freeze

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

This class inherits a constructor from X::Resource

Instance Attribute Details

#created_at ⇒ Time? (readonly)

The time when the space was created

Examples:

Get the creation time

space.created_at

Returns:

  • (Time, nil) —

    the creation time



155
 
# File 'x-objects/lib/x/objects/space.rb', line 155

attribute :created_at, :time

#creator_id ⇒ Integer? (readonly)

The identifier of the creator

Examples:

Get the creator identifier

space.creator_id

Returns:

  • (Integer, nil) —

    the creator identifier



226
 
# File 'x-objects/lib/x/objects/space.rb', line 226

attribute :creator_id, :integer

#ended_at ⇒ Time? (readonly)

The time when the space ended

Examples:

Get the end time

space.ended_at

Returns:

  • (Time, nil) —

    the end time



171
 
# File 'x-objects/lib/x/objects/space.rb', line 171

attribute :ended_at, :time

#host_ids ⇒ Array<Integer> (readonly)

The identifiers of the hosts

Examples:

Get the host identifiers

space.host_ids

Returns:

  • (Array<Integer>) —

    the host identifiers, empty if there are none



234
 
# File 'x-objects/lib/x/objects/space.rb', line 234

attribute :host_ids, :integers

#invited_user_ids ⇒ Array<Integer> (readonly)

The identifiers of the invited users

Examples:

Get the invited user identifiers

space.invited_user_ids

Returns:

  • (Array<Integer>) —

    the invited user identifiers, empty if there are none



250
 
# File 'x-objects/lib/x/objects/space.rb', line 250

attribute :invited_user_ids, :integers

#lang ⇒ String? (readonly)

The BCP 47 language tag

Examples:

Get the language

space.lang

Returns:

  • (String, nil) —

    the language tag



147
 
# File 'x-objects/lib/x/objects/space.rb', line 147

attribute :lang

#participant_count ⇒ Integer? (readonly)

The number of participants

Examples:

Get the participant count

space.participant_count

Returns:

  • (Integer, nil) —

    the participant count



210
 
# File 'x-objects/lib/x/objects/space.rb', line 210

attribute :participant_count, :integer

#scheduled_start ⇒ Time? (readonly)

The scheduled start time

Examples:

Get the scheduled start time

space.scheduled_start

Returns:

  • (Time, nil) —

    the scheduled start time



179
 
# File 'x-objects/lib/x/objects/space.rb', line 179

attribute :scheduled_start, :time

#speaker_ids ⇒ Array<Integer> (readonly)

The identifiers of the speakers

Examples:

Get the speaker identifiers

space.speaker_ids

Returns:

  • (Array<Integer>) —

    the speaker identifiers, empty if there are none



242
 
# File 'x-objects/lib/x/objects/space.rb', line 242

attribute :speaker_ids, :integers

#started_at ⇒ Time? (readonly)

The time when the space started

Examples:

Get the start time

space.started_at

Returns:

  • (Time, nil) —

    the start time



163
 
# File 'x-objects/lib/x/objects/space.rb', line 163

attribute :started_at, :time

#state ⇒ String? (readonly)

The state: live, scheduled, or ended

Examples:

Get the state

space.state

Returns:

  • (String, nil) —

    the state



139
 
# File 'x-objects/lib/x/objects/space.rb', line 139

attribute :state

#subscriber_count ⇒ Integer? (readonly)

The number of subscribers

Examples:

Get the subscriber count

space.subscriber_count

Returns:

  • (Integer, nil) —

    the subscriber count



218
 
# File 'x-objects/lib/x/objects/space.rb', line 218

attribute :subscriber_count, :integer

#ticketed ⇒ Boolean? (readonly)

Whether the space requires a ticket, the is_ticketed field

Examples:

Check whether a space is ticketed

space.ticketed?

Returns:

  • (Boolean, nil) —

    true if the space is ticketed



195
 
# File 'x-objects/lib/x/objects/space.rb', line 195

attribute :ticketed, :boolean, key: %w[is_ticketed]

#title ⇒ String? (readonly)

The title

Examples:

Get the title

space.title

Returns:

  • (String, nil) —

    the title



131
 
# File 'x-objects/lib/x/objects/space.rb', line 131

attribute :title

#topic_ids ⇒ Array<Integer> (readonly)

The identifiers of the topics

Examples:

Get the topic identifiers

space.topic_ids

Returns:

  • (Array<Integer>) —

    the topic identifiers, empty if there are none



258
 
# File 'x-objects/lib/x/objects/space.rb', line 258

attribute :topic_ids, :integers

#updated_at ⇒ Time? (readonly)

The time when the space was last updated

Examples:

Get the update time

space.updated_at

Returns:

  • (Time, nil) —

    the update time



187
 
# File 'x-objects/lib/x/objects/space.rb', line 187

attribute :updated_at, :time

Class Method Details

.default_params ⇒ Hash{String => Array<String>}

The default query parameters requesting every space field and expansion

Examples:

Get the default parameters

X::Space.default_params["space.fields"]

Returns:

  • (Hash{String => Array<String>}) —

    the default query parameters



83
84
85
 
# File 'x-objects/lib/x/objects/space.rb', line 83

def default_params
  {"space.fields" => FIELDS, "user.fields" => User::FIELDS, "topic.fields" => Topic::FIELDS, "expansions" => EXPANSIONS}
end

.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params) {|problem| ... } ⇒ Array<Space>

Look up the live and scheduled spaces many users created, in parallel batches

The API returns the spaces of up to 100 users at a time, in one response without pages, so the users are looked up that many at a time.

Examples:

Print the spaces two users created

X::Space.find_all_by_creator([7505382, 783214], client: client).each { |space| puts space.title }

Parameters:

  • users (Array<User, String, Integer>) —

    the users who created the spaces, or their identifiers

  • client (Object) —

    the client used to make the requests

  • concurrency (Integer) (defaults to: BatchFinders::DEFAULT_CONCURRENCY) —

    the number of batches looked up at once, which must be at least one

  • params (Hash) —

    query parameters merged over the default parameters

Yield Parameters:

  • problem (Problem) —

    each problem the API reported

Returns:

  • (Array<Space>) —

    the spaces, frozen, empty if the users created none

Raises:

  • (ArgumentError) —

    if a user is not a user or the identifier of one, or the concurrency is less than one, before a request



119
120
121
122
123
 
# File 'x-objects/lib/x/objects/space.rb', line 119

def self.find_all_by_creator(users, client:, concurrency: BatchFinders::DEFAULT_CONCURRENCY, **params, &)
  ids = users.map { |user| Utils.id_of(user, User) }
  spaces = lookup_in_batches("spaces/by/creator_ids", :user_ids, ids, client:, concurrency:, **params, &) #: Array[Space]
  spaces.freeze
end

.search(query, client:, **params) ⇒ Cursor

Search spaces by their titles

The API returns the matching spaces in one response, of up to 100 spaces.

Examples:

Print the live spaces about Ruby

X::Space.search("ruby", client: client, state: "live").each { |space| puts space.title }

Parameters:

  • query (String) —

    the search query

  • client (Object) —

    the client used to make the request

  • params (Hash) —

    query parameters merged over the default parameters, such as state: live or scheduled

Returns:

  • (Cursor) —

    a cursor over the matching spaces



98
99
100
 
# File 'x-objects/lib/x/objects/space.rb', line 98

def search(query, client:, **params)
  Cursor.__send__(:build, self, "spaces/search", client:, params: {query:, max_results: MAX_RESULTS}.merge(params), app_only: true)
end

Instance Method Details

#buyers(**params) ⇒ Cursor

The users who bought a ticket to this space

The authenticated user must have created the space. The endpoint takes only OAuth 2.0 user context, which the object layer cannot route around, so a client that signs with OAuth 1.0a, or authenticates as the app, is refused.

Examples:

Print the buyers of a ticketed space

space.buyers.each { |user| puts user.username }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the buyers



321
 
# File 'x-objects/lib/x/objects/space.rb', line 321

def buyers(**params) = cursor(User, "spaces/#{id}/buyers", max_results: MAX_RESULTS, **params)

#creator ⇒ User?

The creator, resolved from the includes or as a stub holding only its identifier

Examples:

Get the creator's username

space.creator.username

Returns:

  • (User, nil) —

    the creator



266
 
# File 'x-objects/lib/x/objects/space.rb', line 266

reference :creator, :User, key: %w[creator_id]

#hosts ⇒ Array<User>

The hosts, resolved from the includes or as stubs holding only their identifiers

Examples:

Get the hosts

space.hosts

Returns:

  • (Array<User>) —

    the hosts



274
 
# File 'x-objects/lib/x/objects/space.rb', line 274

references :hosts, :User, key: %w[host_ids]

#invited_users ⇒ Array<User>

The invited users, from the includes or as stubs holding only their identifiers

Examples:

Get the invited users

space.invited_users

Returns:

  • (Array<User>) —

    the invited users



290
 
# File 'x-objects/lib/x/objects/space.rb', line 290

references :invited_users, :User, key: %w[invited_user_ids]

#posts(**params) ⇒ Cursor Also known as: tweets

The posts shared in this space

Examples:

Print the shared posts

space.posts.each { |post| puts post.text }

Parameters:

  • params (Hash) —

    query parameters merged over the default parameters

Returns:

  • (Cursor) —

    a cursor over the posts



307
308
309
 
# File 'x-objects/lib/x/objects/space.rb', line 307

def posts(**params)
  cursor(Post, "spaces/#{id}/tweets", max_results: MAX_RESULTS, app_only: true, **params)
end

#speakers ⇒ Array<User>

The speakers, from the includes or as stubs holding only their identifiers

Examples:

Get the speakers

space.speakers

Returns:

  • (Array<User>) —

    the speakers



282
 
# File 'x-objects/lib/x/objects/space.rb', line 282

references :speakers, :User, key: %w[speaker_ids]

#ticketed? ⇒ Boolean

Check whether the space requires a ticket

Examples:

Check whether a space is ticketed

space.ticketed?

Returns:

  • (Boolean) —

    true if the space is ticketed




# File 'x-objects/lib/x/objects/space.rb', line 197

#topics ⇒ Array<Topic>

The topics, from the includes or as stubs holding only their identifiers

Examples:

Get the names of the topics

space.topics.map(&:name)

Returns:

  • (Array<Topic>) —

    the topics



298
 
# File 'x-objects/lib/x/objects/space.rb', line 298

references :topics, :Topic, key: %w[topic_ids]