async-matrix 0.1.3 → 1.0.0

data/data/matrix-spec/event-schemas/schema/m.room.member.yaml

@@ -0,0 +1,174 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/state_event.yaml
+description: |-
+  Adjusts the membership state for a user in a room. It is preferable to use the membership APIs
+  (`/rooms/<room id>/invite` etc) when performing membership actions rather than adjusting the
+  state directly as there are a restricted set of valid transformations. For example, user A cannot
+  force user B to join a room, and trying to force this state change directly will fail.
+
+  The following membership states are specified:
+
+  - `invite` - The user has been invited to join a room, but has not yet joined it. They may not
+    participate in the room until they join.
+  - `join` - The user has joined the room (possibly after accepting an invite), and may participate
+    in it.
+  - `leave` - The user was once joined to the room, but has since left (possibly by choice, or
+    possibly by being kicked).
+  - `ban` - The user has been banned from the room, and is no longer allowed to join it until they
+    are un-banned from the room (by having their membership state set to a value other than `ban`).
+  - `knock` - The user has knocked on the room, requesting permission to participate. They may not
+    participate in the room until they join.
+
+  The `third_party_invite` property will be set if this invite is an `invite` event and is the
+  successor of an [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite) event,
+  and absent otherwise.
+
+  This event may also include an `invite_room_state` key inside the event's `unsigned` data.
+  If present, this contains an array of [stripped state events](/client-server-api/#stripped-state)
+  to assist the receiver in identifying the room.
+
+  The user for which a membership applies is represented by the `state_key`. Under some conditions,
+  the `sender` and `state_key` may not match - this may be interpreted as the `sender` affecting
+  the membership state of the `state_key` user.
+
+  The `membership` for a given user can change over time. The table below represents the various changes
+  over time and how clients and servers must interpret those changes. Previous membership can be retrieved
+  from the `prev_content` object on an event. If not present, the user's previous membership must be assumed
+  as `leave`.
+
+  |                   | to `invite`          | to `join`                              | to `leave`                                                                                                                              | to `ban`                    | to `knock`           |
+  |-------------------|----------------------|----------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------|-----------------------------|----------------------|
+  | **from `invite`** | No change.           | User joined the room.                  | If the `state_key` is the same as the `sender`, the user rejected the invite. Otherwise, the `state_key` user had their invite revoked. | User was banned.            | User is re-knocking. |
+  | **from `join`**   | Must never happen.   | `displayname` or `avatar_url` changed. | If the `state_key` is the same as the `sender`, the user left. Otherwise, the `state_key` user was kicked.                              | User was kicked and banned. | Must never happen.   |
+  | **from `leave`**  | New invitation sent. | User joined.                           | No change.                                                                                                                              | User was banned.            | User is knocking.    |
+  | **from `ban`**    | Must never happen.   | Must never happen.                     | User was unbanned.                                                                                                                      | No change.                  | Must never happen.   |
+  | **from `knock`**  | Knock accepted.      | Must never happen.                     | If the `state_key` is the same as the `sender`, the user retracted the knock. Otherwise, the `state_key` user had their knock denied.   | User was banned.            | No change.           |
+
+properties:
+  content:
+    properties:
+      avatar_url:
+        description: 'The avatar URL for this user, if any.'
+        type: string
+        format: uri
+      displayname:
+        description: 'The display name for this user, if any.'
+        type:
+          - "string"
+          - "null"
+      membership:
+        description: The membership state of the user.
+        enum:
+          - invite
+          - join
+          - knock
+          - leave
+          - ban
+        type: string
+      is_direct:
+        description: |-
+          Flag indicating if the room containing this event was created with the intention of being
+          a direct chat. See [Direct Messaging](/client-server-api/#direct-messaging).
+        type: boolean
+      join_authorised_via_users_server:
+        x-addedInMatrixVersion: "1.2"
+        type: string
+        format: mx-user-id
+        pattern: "^@"
+        description: |-
+          Usually found on `join` events, this field is used to denote which homeserver (through
+          representation of a user with sufficient power level) authorised the user's join. More
+          information about this field can be found in the [Restricted Rooms Specification](/client-server-api/#restricted-rooms).
+
+          Client and server implementations should be aware of the [signing implications](/rooms/v8/#authorization-rules)
+          of including this field in further events: in particular, the event must be signed by the
+          server which owns the user ID in the field. When copying the membership event's `content`
+          (for profile updates and similar) it is therefore encouraged to exclude this field in the
+          copy, as otherwise the event might fail event authorization.
+      reason:
+        x-addedInMatrixVersion: "1.1"
+        type: string
+        description: |-
+          Optional user-supplied text for why their membership has changed. For kicks and bans,
+          this is typically the reason for the kick or ban. For other membership changes, this is a
+          way for the user to communicate their intent without having to send a message to the
+          room, such as in a case where Bob rejects an invite from Alice about an upcoming concert,
+          but can't make it that day.
+
+          Clients are not recommended to show this reason to users when receiving an invite due to
+          the potential for spam and abuse. Hiding the reason behind a button or other component is
+          recommended.
+      third_party_invite:
+        title: ThirdPartyInvite
+        description: |-
+          A third-party invite, if this `m.room.member` is the successor to an
+          [`m.room.third_party_invite`](/client-server-api/#mroomthird_party_invite)
+          event.
+        type: object
+        properties:
+          display_name:
+            description: |-
+              A name which can be displayed to represent the user instead of their
+              third-party identifier
+            type: string
+          signed:
+            $ref: components/signed_third_party_invite.yaml
+        required:
+          - display_name
+          - signed
+    required:
+      - membership
+    title: EventContent
+    type: object
+  state_key:
+    description: |-
+      The `user_id` this membership event relates to. In all cases except for when `membership` is
+      `join`, the user ID sending the event does not need to match the user ID in the `state_key`,
+      unlike other events. Regular authorisation rules still apply.
+    type: string
+    format: mx-user-id
+    pattern: "^@"
+  type:
+    enum:
+      - m.room.member
+    type: string
+  unsigned:
+    allOf:
+      - $ref: "core-event-schema/unsigned_prop.yaml"
+      - type: object
+        properties:
+          invite_room_state:
+            x-changedInMatrixVersion:
+              "1.16": |
+                `m.room.create` was made a required event type for stripped state.
+            description: |-
+              A subset of the state of the room at the time of the invite, if `membership` is `invite`.
+              Note that this state is informational, and SHOULD NOT be trusted; once the client has
+              joined the room, it SHOULD fetch the live state from the server and discard the
+              invite_room_state. Also, clients must not rely on any particular state being present here;
+              they SHOULD behave properly (with possibly a degraded but not a broken experience) in
+              the absence of any particular events here. If they are set on the room, at least the
+              state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, and `m.room.name`
+              SHOULD be included. The `m.room.create` event MUST be included, though MAY be missing if
+              the server hasn't updated to support the Matrix 1.16 specification.
+            items:
+              $ref: "core-event-schema/stripped_state.yaml"
+            type: array
+          knock_room_state:
+            x-changedInMatrixVersion:
+              "1.16": |
+                `m.room.create` was made a required event type for stripped state.
+            description: |-
+              A subset of the state of the room at the time of the knock, if `membership` is `knock`.
+              This has the same restrictions as `invite_room_state`. If they are set on the room, at least
+              the state for `m.room.avatar`, `m.room.canonical_alias`, `m.room.join_rules`, `m.room.name`,
+              and `m.room.encryption` SHOULD be included. The `m.room.create` event MUST be included,
+              though MAY be missing if the server hasn't updated to support the Matrix 1.16 specification.
+            items:
+              $ref: "core-event-schema/stripped_state.yaml"
+            type: array
+title: The current membership state of a user in the room.
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.audio.yaml

@@ -0,0 +1,73 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message represents a single audio clip.
+properties:
+  content:
+    properties:
+      body:
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the audio.
+        type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the audio.
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      info:
+        description: Metadata for the audio clip referred to in `url`.
+        properties:
+          duration:
+            description: The duration of the audio in milliseconds.
+            type: integer
+          mimetype:
+            description: The mimetype of the audio e.g. `audio/aac`.
+            type: string
+          size:
+            description: The size of the audio clip in bytes.
+            type: integer
+        title: AudioInfo
+        type: object
+      msgtype:
+        enum:
+          - m.audio
+        type: string
+      url:
+        description: |-
+          Required if the file is unencrypted. The URL (typically [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris))
+          to the audio clip.
+        type: string
+      file:
+        description: |-
+          Required if the file is encrypted. Information on the encrypted
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+        title: EncryptedFile
+        type: object
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: AudioMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.emote.yaml

@@ -0,0 +1,36 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: "This message is similar to `m.text` except that the sender is 'performing' the action contained in the `body` key, similar to `/me` in IRC. This message should be prefixed by the name of the sender. This message could also be represented in a different colour to distinguish it from regular `m.text` messages."
+properties:
+  content:
+    properties:
+      body:
+        description: The emote action to perform.
+        type: string
+      msgtype:
+        enum:
+          - m.emote
+        type: string
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the `body`. This is required if `format`
+          is specified.
+        type: string
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: EmoteMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.file.yaml

@@ -0,0 +1,85 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message represents a generic file.
+properties:
+  content:
+    properties:
+      body:
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the file.
+        type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the file.
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+      info:
+        description: Information about the file referred to in `url`.
+        properties:
+          mimetype:
+            description: The mimetype of the file e.g. `application/msword`.
+            type: string
+          size:
+            description: The size of the file in bytes.
+            type: integer
+          thumbnail_url:
+            description: |-
+              The URL to the thumbnail of the file. Only present if the
+              thumbnail is unencrypted.
+            type: string
+          thumbnail_file:
+            description: |-
+              Information on the encrypted thumbnail file, as specified in
+              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+              Only present if the thumbnail is encrypted.
+            title: EncryptedFile
+            type: object
+          thumbnail_info:
+            allOf:
+              - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
+            description: Metadata about the image referred to in `thumbnail_url`.
+        title: FileInfo
+        type: object
+      msgtype:
+        enum:
+          - m.file
+        type: string
+      url:
+        description: |-
+          Required if the file is unencrypted. The URL (typically [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris))
+          to the file.
+        type: string
+      file:
+        description: |-
+          Required if the file is encrypted. Information on the encrypted
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+        title: EncryptedFile
+        type: object
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: FileMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.image.yaml

@@ -0,0 +1,63 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message represents a single image and an optional thumbnail.
+properties:
+  content:
+    properties:
+      body:
+        description: |-
+          If `filename` is not set or the value of both properties are
+          identical, this is the filename of the original upload. Otherwise,
+          this is a caption for the image.
+        type: string
+        x-changedInMatrixVersion:
+          "1.10": This property can act as a caption for the image.
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      formatted_body:
+        description: |-
+          The formatted version of the `body`, when it acts as a caption. This
+          is required if `format` is specified.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      filename:
+        description: The original filename of the uploaded file.
+        type: string
+        x-addedInMatrixVersion: "1.10"
+      info:
+        allOf:
+          - $ref: core-event-schema/msgtype_infos/image_info.yaml
+        description: Metadata about the image referred to in `url`.
+      msgtype:
+        enum:
+          - m.image
+        type: string
+      url:
+        description: |-
+          Required if the file is unencrypted. The URL (typically [`mxc://` URI](/client-server-api/#matrix-content-mxc-uris))
+          to the image.
+        type: string
+      file:
+        description: |-
+          Required if the file is encrypted. Information on the encrypted
+          file, as specified in
+          [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+        title: EncryptedFile
+        type: object
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: ImageMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.key.verification.request.yaml

@@ -0,0 +1,70 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description:
+  Requests a key verification in a room.  When requesting a key verification
+  using to-device messaging, an event with type [`m.key.verification.request`](/client-server-api/#mkeyverificationrequest)
+  should be used.
+properties:
+  content:
+    properties:
+      body:
+        type: string
+        description: |-
+          A fallback message to alert users that their client does not support
+          the key verification framework, and that they should use a different method
+          to verify keys.  For example, "Alice is requesting to verify keys with you.
+          However, your client does not support this method, so you will need to use
+          the legacy method of key verification."
+
+          Clients that do support the key verification framework should hide the body
+          and instead present the user with an interface to accept or reject the key
+          verification.
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the `body`. This is required if `format` is
+          specified.  As with the `body`, clients that do support the key
+          verification framework should hide the formatted body and instead
+          present the user with an interface to accept or reject the key
+          verification.
+        type: string
+      from_device:
+        type: string
+        description: |-
+          The device ID which is initiating the request.
+      methods:
+        type: array
+        description: |-
+          The verification methods supported by the sender.
+        items:
+          type: string
+      to:
+        description: |-
+          The user that the verification request is intended for.  Users who
+          are not named in this field and who did not send this event should
+          ignore all other events that have an `m.reference` relationship with
+          this event.
+        type: string
+      msgtype:
+        enum:
+          - m.key.verification.request
+        type: string
+    required:
+      - from_device
+      - methods
+      - msgtype
+      - to
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: KeyVerification
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.location.yaml

@@ -0,0 +1,50 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message represents a real-world location.
+properties:
+  content:
+    properties:
+      body:
+        description: "A description of the location e.g. 'Big Ben, London, UK', or some kind of content description for accessibility e.g. 'location attachment'."
+        type: string
+      geo_uri:
+        description: A [geo URI (RFC5870)](https://datatracker.ietf.org/doc/html/rfc5870) representing this location.
+        type: string
+      msgtype:
+        enum:
+          - m.location
+        type: string
+      info:
+        type: object
+        properties:
+          thumbnail_url:
+            description: |-
+              The URL to a thumbnail of the location being represented.
+              Only present if the thumbnail is unencrypted.
+            type: string
+          thumbnail_file:
+            description: |-
+              Information on the encrypted thumbnail file, as specified in
+              [End-to-end encryption](/client-server-api/#sending-encrypted-attachments).
+              Only present if the thumbnail is encrypted.
+            title: EncryptedFile
+            type: object
+          thumbnail_info:
+            allOf:
+              - $ref: core-event-schema/msgtype_infos/thumbnail_info.yaml
+            description:  Metadata about the image referred to in `thumbnail_url`.
+        title: LocationInfo
+    required:
+      - msgtype
+      - body
+      - geo_uri
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: LocationMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.notice.yaml

@@ -0,0 +1,36 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: 'The `m.notice` type is primarily intended for responses from automated clients. An `m.notice` message must be treated the same way as a regular `m.text` message with two exceptions. Firstly, clients should present `m.notice` messages to users in a distinct manner, and secondly, `m.notice` messages must never be automatically responded to. This helps to prevent infinite-loop situations where two automated clients continuously exchange messages.'
+properties:
+  content:
+    properties:
+      body:
+        description: The notice text to send.
+        type: string
+      msgtype:
+        enum:
+          - m.notice
+        type: string
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the `body`. This is required if `format`
+          is specified.
+        type: string
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: NoticeMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.server_notice.yaml

@@ -0,0 +1,41 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: Represents a server notice for a user.
+properties:
+  content:
+    properties:
+      body:
+        description: A human-readable description of the notice.
+        type: string
+      msgtype:
+        enum:
+          - m.server_notice
+        type: string
+      server_notice_type:
+        description: |-
+          The type of notice being represented.
+        type: string
+      admin_contact:
+        description: |-
+          A URI giving a contact method for the server administrator. Required if the
+          notice type is `m.server_notice.usage_limit_reached`.
+        type: string
+      limit_type:
+        description: |-
+          The kind of usage limit the server has exceeded. Required if the notice type is
+          `m.server_notice.usage_limit_reached`.
+        type: string
+    required:
+      - msgtype
+      - body
+      - server_notice_type
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: ServerNoticeMessage
+type: object

data/data/matrix-spec/event-schemas/schema/m.room.message$m.text.yaml

@@ -0,0 +1,36 @@
+---
+$schema: https://json-schema.org/draft/2020-12/schema
+
+allOf:
+  - $ref: core-event-schema/room_event.yaml
+description: This message is the most basic message and is used to represent text.
+properties:
+  content:
+    properties:
+      body:
+        description: The body of the message.
+        type: string
+      msgtype:
+        enum:
+          - m.text
+        type: string
+      format:
+        description: |-
+          The format used in the `formatted_body`. This is required if `formatted_body`
+          is specified. Currently only `org.matrix.custom.html` is supported.
+        type: string
+      formatted_body:
+        description: |-
+          The formatted version of the `body`. This is required if `format`
+          is specified.
+        type: string
+    required:
+      - msgtype
+      - body
+    type: object
+  type:
+    enum:
+      - m.room.message
+    type: string
+title: TextMessage
+type: object