async-matrix 3.0.1 → 4.0.0

data/lib/async/matrix/api/client_server/support.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/support"
+
+module Async
+  module Matrix
+    module ClientServer
+      # The contacts a homeserver publishes.
+      #
+      # The endpoint arrived in v1.10, so the fields are read by that layer.
+      class SupportContacts < Representation
+        include Versioned
+      end
+
+      # Who to contact about a homeserver.
+      class Support
+        include Versioned
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [Support] the contacts.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/sync.rb

@@ -0,0 +1,179 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "console"
+
+require_relative "../../events"
+require_relative "../../paths"
+require_relative "../../representation"
+require_relative "rooms"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/sync"
+
+module Async
+  module Matrix
+    module ClientServer
+      # A single sync batch: the delta since the previous one.
+      #
+      # `/sync` is a long poll, so a loop is a sequence of requests, each starting from the last {#next_batch}.
+      class Sync < Representation
+        include Versioned
+
+        # How long the server should hold a sync request open, in milliseconds.
+        DEFAULT_TIMEOUT = 30_000
+
+        # The absolute path of the sync endpoint.
+        #
+        # @returns [String] the path.
+        def self.path
+          "#{V3}/sync"
+        end
+
+        # Begin syncing.
+        #
+        # @parameter resource [Async::REST::Resource] an authenticated resource, typically a {Client}.
+        # @parameter since [String | nil] the batch token to start from, or nil for the initial sync.
+        # @parameter timeout [Integer] how long the server should wait, in milliseconds.
+        # @returns [Sync] the first batch.
+        def self.start(resource, since: nil, timeout: DEFAULT_TIMEOUT, **parameters)
+          parameters[:timeout] = timeout
+          if since
+            parameters[:since] = since
+          end
+
+          self.get(resource.with(path: self.path, parameters: parameters))
+        end
+
+        # @returns [String] the token which the following batch should start from.
+        def next_batch
+          self.value[:next_batch]
+        end
+
+        # @returns [Hash] the rooms the user has joined, keyed by room ID.
+        def joined
+          self.value.dig(:rooms, :join) || {}
+        end
+
+        # @returns [Hash] the rooms the user has been invited to, keyed by room ID.
+        def invited
+          self.value.dig(:rooms, :invite) || {}
+        end
+
+        # @returns [Hash] the events addressed to this device, which carry encryption keys.
+        def to_device
+          self.value.dig(:to_device, :events) || []
+        end
+
+        # @returns [Array(String)] the users whose device lists changed.
+        def changed_devices
+          self.value.dig(:device_lists, :changed) || []
+        end
+
+        # @returns [Array(String)] the users who are no longer shared with.
+        def left_devices
+          self.value.dig(:device_lists, :left) || []
+        end
+
+        # @returns [Hash] how many one time keys the server still holds, by algorithm.
+        def one_time_keys_count
+          self.value[:device_one_time_keys_count] || {}
+        end
+
+        # @returns [Boolean] whether anything happened in this batch.
+        def empty?
+          self.joined.empty? and self.invited.empty?
+        end
+
+        # Enumerate over every timeline event in this batch.
+        #
+        # Note that the room IDs are symbols, because the JSON parser symbolizes all names, so they are converted back to strings here.
+        #
+        # @yields {|event| ...}
+        #   @parameter event [Events::Envelope] the event, which names the room it came from.
+        def each_event
+          if block_given?
+            registry = Events.registry(self.version)
+
+            self.joined.each do |room_id, room|
+              events = room.dig(:timeline, :events) or next
+
+              events.each do |event|
+                # `/sync` groups events by room rather than naming the room on each one, so the envelope is told which room it came from:
+                yield registry.wrap(event, room_id: room_id.to_s)
+              end
+            end
+          else
+            to_enum(:each_event)
+          end
+        end
+
+        # Enumerate over every message in this batch.
+        #
+        # @yields {|event| ...}
+        #   @parameter event [Events::Envelope] the message, whose content is an {Events::Message}.
+        def each_message
+          if block_given?
+            self.each_event do |event|
+              unless event.content.is_a?(Events::Message)
+                next
+              end
+
+              yield event
+            end
+          else
+            to_enum(:each_message)
+          end
+        end
+
+        # The following batch, continuing from this one. This will block until the server has something to report, or until the timeout expires.
+        #
+        # @parameter timeout [Integer] how long the server should wait, in milliseconds.
+        # @returns [Sync] the following batch.
+        def following(timeout: DEFAULT_TIMEOUT, **parameters)
+          parameters[:since] = self.next_batch
+          parameters[:timeout] = timeout
+
+          self.class.get(@resource.with(parameters: parameters))
+        end
+
+        # Sync repeatedly, yielding each batch as it arrives. This does not return.
+        #
+        # Resuming after a failure costs nothing: the batch which failed to arrive leaves this one holding the cursor.
+        #
+        # @parameter retries [Integer] how many times to ask again before giving up.
+        # @parameter backoff [Numeric] how long to wait before the first retry, doubling after each.
+        # @yields {|sync| ...}
+        #   @parameter sync [Sync] the batch.
+        def each(retries: 0, backoff: 0.5, **options)
+          if block_given?
+            sync = self
+            attempts = 0
+
+            while true
+              yield sync
+
+              begin
+                sync = sync.following(**options)
+                attempts = 0
+              rescue => error
+                attempts += 1
+
+                if attempts > retries
+                  raise
+                end
+
+                Console.warn(self, "Sync was interrupted; resuming.", since: sync.next_batch, attempt: attempts, error: error)
+
+                sleep(backoff * (2 ** (attempts - 1)))
+              end
+            end
+          else
+            to_enum(:each, retries: retries, backoff: backoff, **options)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/tags.rb

@@ -0,0 +1,102 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "protocol/url/encoding"
+
+require_relative "../../paths"
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/tags"
+
+module Async
+  module Matrix
+    module ClientServer
+      # The tags on one room.
+      class RoomTags < Representation
+        include Versioned
+
+        # @returns [Hash] the tags, by name, each carrying the order the user gave it.
+        def tags
+          self.value[:tags] || {}
+        end
+
+        # @returns [Array(Symbol)] the names of the tags.
+        def names
+          self.tags.keys
+        end
+
+        # @returns [Boolean] whether the room has none.
+        def empty?
+          self.tags.empty?
+        end
+      end
+
+      # The tags a user has put on their rooms.
+      class Tags
+        include Versioned
+
+        # @parameter user_id [String] the user whose tags they are.
+        # @parameter room_id [String] the room they are on.
+        # @returns [String] the path of the tags on that room.
+        def self.path_for(user_id, room_id)
+          "#{V3}/user/#{::Protocol::URL::Encoding.escape(user_id)}/rooms/#{::Protocol::URL::Encoding.escape(room_id)}/tags"
+        end
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [Tags] the tags.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        # The tags this user has put on a room.
+        #
+        # @parameter user_id [String] the user whose tags they are.
+        # @parameter room_id [String] the room to read them for.
+        # @returns [RoomTags] the tags.
+        def get_room_tags(user_id, room_id)
+          api::RoomTags.get(@resource.with(path: self.class.path_for(user_id, room_id)))
+        end
+
+        # Put a tag on a room.
+        #
+        # @parameter user_id [String] the user whose tag it is.
+        # @parameter room_id [String] the room to tag.
+        # @parameter tag [String] the tag, e.g. `m.favourite`.
+        # @parameter order [Float | nil] where the room sorts among the others with this tag.
+        # @returns [Representation] the empty response.
+        def set_room_tag(user_id, room_id, tag, order: nil)
+          payload = {order: order}.compact
+          path = "#{self.class.path_for(user_id, room_id)}/#{::Protocol::URL::Encoding.escape(tag)}"
+
+          api::Representation.put(@resource.with(path: path), payload)
+        end
+
+        # Take a tag off a room.
+        #
+        # @parameter user_id [String] the user whose tag it is.
+        # @parameter room_id [String] the room to untag.
+        # @parameter tag [String] the tag to remove.
+        # @returns [Representation] the empty response.
+        def delete_room_tag(user_id, room_id, tag)
+          path = "#{self.class.path_for(user_id, room_id)}/#{::Protocol::URL::Encoding.escape(tag)}"
+
+          api::Representation.delete(@resource.with(path: path))
+        end
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/third_party_lookup.rb

@@ -0,0 +1,160 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "protocol/url/encoding"
+
+require_relative "../../paths"
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/third_party_lookup"
+
+module Async
+  module Matrix
+    module ClientServer
+      # The protocols a homeserver bridges to.
+      class Protocols < Representation
+        include Versioned
+
+        # @returns [Hash] the protocols, by name, each describing what it can be asked for.
+        def protocols
+          self.value
+        end
+
+        # @returns [Array(Symbol)] the names of the protocols.
+        def names
+          self.value.keys
+        end
+
+        # @returns [Boolean] whether the homeserver bridges to none.
+        def empty?
+          self.value.empty?
+        end
+      end
+
+      # What one protocol can be asked for.
+      class Protocol < Representation
+        include Versioned
+
+        # @returns [Array(Hash)] the fields which name a user on this network.
+        def user_fields
+          self.value[:user_fields] || []
+        end
+
+        # @returns [Array(Hash)] the fields which name a room on this network.
+        def location_fields
+          self.value[:location_fields] || []
+        end
+
+        # @returns [Hash] what each field means.
+        def field_types
+          self.value[:field_types] || {}
+        end
+
+        # @returns [Array(Hash)] the instances of this network the homeserver knows.
+        def instances
+          self.value[:instances] || []
+        end
+      end
+
+      # The rooms or the users a lookup found.
+      class ThirdPartyEntries < Representation
+        include Versioned
+
+        # @returns [Array(Hash)] the entries, which the specification sends as a list.
+        def entries
+          self.value
+        end
+
+        # @returns [Boolean] whether it found nothing.
+        def empty?
+          self.entries.empty?
+        end
+      end
+
+      # The networks an application service bridges to.
+      class ThirdPartyLookup
+        include Versioned
+
+        # @returns [String] the path of what the homeserver bridges to.
+        def self.path
+          "#{V3}/thirdparty"
+        end
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [ThirdPartyLookup] the networks.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        # The protocols this homeserver bridges to.
+        #
+        # @returns [Protocols] the protocols.
+        def get_protocols
+          api::Protocols.get(@resource.with(path: "#{self.class.path}/protocols"))
+        end
+
+        # What one protocol can be asked for.
+        #
+        # @parameter protocol [String] the protocol to describe.
+        # @returns [Protocol] what it can be asked for.
+        def get_protocol_metadata(protocol)
+          path = "#{self.class.path}/protocol/#{::Protocol::URL::Encoding.escape(protocol)}"
+
+          api::Protocol.get(@resource.with(path: path))
+        end
+
+        # The room an alias on a bridged network names.
+        #
+        # @parameter alias_name [String] the Matrix alias to resolve.
+        # @returns [ThirdPartyEntries] the rooms it found.
+        def query_location_by_alias(alias_name)
+          api::ThirdPartyEntries.get(@resource.with(path: "#{self.class.path}/location", parameters: {alias: alias_name}))
+        end
+
+        # The rooms a bridged network has, by its own fields.
+        #
+        # @parameter protocol [String] the protocol to ask.
+        # @parameter fields [Hash] the fields which name the room there.
+        # @returns [ThirdPartyEntries] the rooms it found.
+        def query_location_by_protocol(protocol, **fields)
+          path = "#{self.class.path}/location/#{::Protocol::URL::Encoding.escape(protocol)}"
+
+          api::ThirdPartyEntries.get(@resource.with(path: path, parameters: fields))
+        end
+
+        # The user a Matrix ID names on a bridged network.
+        #
+        # @parameter userid [String] the Matrix user to resolve.
+        # @returns [ThirdPartyEntries] the users it found.
+        def query_user_by_id(userid)
+          api::ThirdPartyEntries.get(@resource.with(path: "#{self.class.path}/user", parameters: {userid: userid}))
+        end
+
+        # The users a bridged network has, by its own fields.
+        #
+        # @parameter protocol [String] the protocol to ask.
+        # @parameter fields [Hash] the fields which name the user there.
+        # @returns [ThirdPartyEntries] the users it found.
+        def query_user_by_protocol(protocol, **fields)
+          path = "#{self.class.path}/user/#{::Protocol::URL::Encoding.escape(protocol)}"
+
+          api::ThirdPartyEntries.get(@resource.with(path: path, parameters: fields))
+        end
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/third_party_membership.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/third_party_membership"
+require_relative "rooms"
+
+module Async
+  module Matrix
+    module ClientServer
+      # Inviting someone to a room by an address rather than a user.
+      class ThirdPartyMembership
+        include Versioned
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [ThirdPartyMembership] the invitations.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        # Invite someone to a room by an email address or a phone number.
+        #
+        # The identity server resolves the address.
+        #
+        # @parameter room_id [String] the room to invite them to.
+        # @parameter id_server [String] the identity server to resolve the address through.
+        # @parameter id_access_token [String] the token for that identity server.
+        # @parameter medium [String] `email` or `msisdn`.
+        # @parameter address [String] the address to invite.
+        # @returns [Representation] the empty response.
+        def invite_by_3pid(room_id, id_server, id_access_token, medium, address)
+          payload = {id_server: id_server, id_access_token: id_access_token, medium: medium, address: address}
+
+          api::Representation.post(@resource.with(path: "#{api::Room.path_for(room_id)}/invite"), payload)
+        end
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/threads_list.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "protocol/url/encoding"
+
+require_relative "../../paths"
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/threads_list"
+
+module Async
+  module Matrix
+    module ClientServer
+      # A page of the events which start threads.
+      #
+      # The endpoint arrived in v1.4, so the fields are read by that layer.
+      class ThreadRoots < Representation
+        include Versioned
+      end
+
+      # The threads of a room.
+      class ThreadsList
+        include Versioned
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [ThreadsList] the threads.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+      end
+    end
+  end
+end

data/lib/async/matrix/api/client_server/to_device.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+# Released under the Apache License, Version 2.0.
+# Copyright, 2026, by General Intelligence Systems.
+
+require "securerandom"
+
+require "protocol/url/encoding"
+
+require_relative "../../paths"
+require_relative "../../representation"
+require_relative "../../versioned"
+require_relative "../../abstract/api/client_server/to_device"
+
+module Async
+  module Matrix
+    module ClientServer
+      # Messages sent to a device rather than into a room.
+      #
+      # This is how encryption keys travel, and they arrive in a sync batch's `to_device`.
+      class ToDevice
+        include Versioned
+
+        # @parameter parent [Async::REST::Resource] the resource to derive from.
+        # @returns [ToDevice] the sender.
+        def self.for(parent)
+          self.new(parent)
+        end
+
+        # @returns [String] a transaction ID, which makes sending idempotent.
+        def self.transaction_id
+          SecureRandom.uuid
+        end
+
+        # @parameter resource [Async::REST::Resource] the resource to make requests against.
+        def initialize(resource)
+          @resource = resource
+        end
+
+        # @attribute [Async::REST::Resource] the resource requests are made against.
+        attr :resource
+
+        def inspect
+          "\#<#{self.class}>"
+        end
+
+        # Send an event to the given devices.
+        #
+        # @parameter type [String] the event type, e.g. `m.room_key`.
+        # @parameter messages [Hash] the content, by user ID and then device ID.
+        # @parameter transaction_id [String] a unique ID which makes this idempotent.
+        # @returns [Representation] the empty response.
+        def send_to_device(type, messages, transaction_id: self.class.transaction_id)
+          path = "#{V3}/sendToDevice/#{::Protocol::URL::Encoding.escape(type)}/#{::Protocol::URL::Encoding.escape(transaction_id)}"
+
+          api::Representation.put(@resource.with(path: path), {messages: messages})
+        end
+      end
+    end
+  end
+end