NAME
    `Net::Async::Matrix' - use Matrix with IO::Async

SYNOPSIS
     use Net::Async::Matrix;
     use IO::Async::Loop;

     my $loop = IO::Async::Loop->new;

     my $matrix = Net::Async::Matrix->new(
        server => "my.home.server",
     );

     $loop->add( $matrix );

     $matrix->login(
        user     => '@my-user:home.server',
        password => 'SeKr1t',
     )->get;

DESCRIPTION
    Matrix is an new open standard for interoperable Instant Messaging and
    VoIP, providing pragmatic HTTP APIs and open source reference
    implementations for creating and running your own real-time
    communication infrastructure.

    This module allows an program to interact with a Matrix homeserver as a
    connected user client.

    http://matrix.org/

EVENTS
    The following events are invoked, either using subclass methods or
    `CODE' references in parameters:

  on_log $message
    A request to write a debugging log message. This is provided temporarily
    for development and debugging purposes, but will at some point be
    removed when the code has reached a certain level of stability.

  on_presence $user, %changes
    Invoked on receipt of a user presence change event from the homeserver.
    `%changes' will map user state field names to 2-element ARRAY
    references, each containing the old and new values of that field.

  on_room_new $room
    Invoked when a new room first becomes known about.

    Passed an instance of Net::Async::Matrix::Room.

  on_room_del $room
    Invoked when the user has now left a room.

  on_invite $event
    Invoked on receipt of a room invite. The `$event' will contain the plain
    Matrix event as received; with at least the keys `inviter' and
    `room_id'.

  on_unknown_event $event
    Invoked on receipt of any sort of event from the event stream, that is
    not recognised by any of the other code. This can be used to handle new
    kinds of incoming events.

PARAMETERS
    The following named parameters may be passed to `new' or `configure'. In
    addition, `CODE' references for event handlers using the event names
    listed above can also be given.

  server => STRING
    Hostname and port number to contact the homeserver at. Given in the form

     $hostname:$port

    This string will be interpolated directly into HTTP request URLs.

  SSL => BOOL
    Whether to use SSL/TLS to communicate with the homeserver. Defaults
    false.

  SSL_* => ...
    Any other parameters whose names begin `SSL_' will be stored for passing
    to the HTTP user agent. See IO::Socket::SSL for more detail.

  path_prefix => STRING
    Optional. Gives the path prefix to find the Matrix client API at.
    Normally this should not need modification.

  on_room_member, on_room_message => CODE
    Optional. Sets default event handlers on new room objects.

  enable_events => BOOL
    Optional. Normally enabled, but if set to a defined-but-false value
    (i.e. 0 or empty string) the event stream will be disabled. This will
    cause none of the incoming event handlers to be invoked, because the
    server will not be polled for events.

    This may be useful in simple send-only cases where the client has no
    interest in receiveing any events, and wishes to reduce the load on the
    homeserver.

  longpoll_timeout => NUM
    Optional. Timeout in seconds for the `/events' longpoll operation.
    Defaults to 30 seconds if not supplied.

METHODS
    The following methods documented with a trailing call to `->get' return
    Future instances.

  $matrix->login( %params )->get
    Performs the necessary steps required to authenticate with the
    configured Home Server, actually obtain an access token and starting the
    event stream (unless disabled by the `enable_events' option being
    false). The returned `Future' will eventually yield the `$matrix' object
    itself, so it can be easily chained.

    There are various methods of logging in supported by Matrix; the
    following sets of arguments determine which is used:

    user_id, password
        Log in via the `m.login.password' method.

    user_id, access_token
        Directly sets the `user_id' and `access_token' fields, bypassing the
        usual login semantics. This presumes you already have an existing
        access token to re-use, obtained by some other mechanism. This
        exists largely for testing purposes.

  $matrix->register( %params )->get
    Performs the necessary steps required to create a new account on the
    configured Home Server.

  $f = $matrix->start
    Performs the initial IMSync on the server, and starts the event stream
    to begin receiving events.

    While this method does return a `Future' it is not required that the
    caller keep track of this; the object itself will store it. It will
    complete when the initial IMSync has fininshed, and the event stream has
    started.

    If the initial sync has already been requested, this method simply
    returns the future it returned the last time, ensuring that you can
    await the client starting up simply by calling it; it will not start a
    second time.

  $matrix->stop
    Stops the event stream. After calling this you will need to use `start'
    again to continue receiving events.

  $user = $matrix->myself
    Returns the user object representing the connected user.

  $user = $matrix->user( $user_id )
    Returns the user object representing a user of the given ID, if defined,
    or `undef'.

  $name = $matrix->get_displayname->get
  $matrix->set_displayname( $name )->get
    Accessor and mutator for the user account's "display name" profile
    field.

  ( $presence, $msg ) = $matrix->get_presence->get
  $matrix->set_presence( $presence, $msg )->get
    Accessor and mutator for the user's current presence state and optional
    status message string.

  ( $room, $room_alias ) = $matrix->create_room( $alias_localpart )->get
    Requests the creation of a new room and associates a new alias with the
    given localpart on the server. The returned `Future' will return an
    instance of Net::Async::Matrix::Room and a string containing the full
    alias that was created.

  $room = $matrix->join_room( $room_alias_or_id )->get
    Requests to join an existing room with the given alias name or plain
    room ID. If this room is already known by the `$matrix' object, this
    method simply returns it.

  $matrix->add_alias( $alias, $room_id )->get
  $matrix->delete_alias( $alias )->get
    Performs a directory server request to create the given room alias name,
    to point at the room ID, or to remove it again.

    Note that this is likely only to be supported for alias names scoped
    within the homeserver the client is connected to, and that additionally
    some form of permissions system may be in effect on the server to limit
    access to the directory server.

  $content_uri = $matrix->upload( %params )->get
    Performs a post to the server's media content repository, to upload a
    new piece of content, returning the content URI that points to it.

    The content can be specified in any of three ways, with the following
    three mutually-exclusive arguments:

    content => STRING
        Gives the content directly as an immediate scalar value.

    file => STRING
        Gives the path to a readable file on the filesystem containing the
        content.

    fh => IO
        Gives an opened IO handle the content can be read from.

    The following additional arguments are also recognised:

    content_type => STRING
        Gives the MIME type of the content data.

    content_length => INT
        Optional. If the content is being delivered from an opened
        filehandle (via the `fh' argument), this gives the total length in
        bytes. This is required in cases such as reading from pipes, when
        the length of the content isn't immediately available such as by
        `stat()'ing the filehandle.

USER STRUCTURES
    Parameters documented as `$user' receive a user struct, which supports
    the following methods:

  $user_id = $user->user_id
    User ID of the user.

  $displayname = $user->displayname
    Profile displayname of the user.

  $presence = $user->presence
    Presence state. One of `offline', `unavailable' or `online'.

  $last_active = $user->last_active
    Epoch time that the user was last active.

SUBCLASSING METHODS
    The following methods are not normally required by users of this class,
    but are provided for the convenience of subclasses to override.

  $room = $matrix->make_room( %params )
    Returns a new instance of Net::Async::Matrix::Room.

SEE ALSO
    *   http://matrix.org/ - matrix.org home page

    *   https://github.com/matrix-org - matrix.org on github

AUTHOR
    Paul Evans <leonerd@leonerd.org.uk>