async-matrix 0.1.2 → 1.0.0

data/data/matrix-spec/api/client-server/tags.yaml

@@ -0,0 +1,183 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server tag API
+  version: 1.0.0
+paths:
+  "/user/{userId}/rooms/{roomId}/tags":
+    get:
+      summary: List the tags for a room.
+      description: List the tags set by a user on a room.
+      operationId: getRoomTags
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The id of the user to get tags for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to get tags for.
+          example: "!726s6s6q:example.com"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The list of tags for the user for the room.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  tags:
+                    type: object
+                    additionalProperties:
+                      $ref: definitions/tag.yaml
+              examples:
+                response:
+                  value: {
+                    "tags": {
+                      "m.favourite": {
+                        "order": 0.1
+                      },
+                      "u.Work": {
+                        "order": 0.7
+                      },
+                      "u.Customers": {}
+                    }
+                  }
+      tags:
+        - User data
+  "/user/{userId}/rooms/{roomId}/tags/{tag}":
+    put:
+      summary: Add a tag to a room.
+      description: Add a tag to the room.
+      operationId: setRoomTag
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The id of the user to add a tag for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to add a tag to.
+          example: "!726s6s6q:example.com"
+          schema:
+            type: string
+        - in: path
+          name: tag
+          required: true
+          description: The tag to add.
+          example: u.work
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/tag.yaml
+        description: Extra data for the tag, e.g. ordering.
+        required: true
+      responses:
+        "200":
+          description: The tag was successfully added.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+      tags:
+        - User data
+    delete:
+      summary: Remove a tag from the room.
+      description: Remove a tag from the room.
+      operationId: deleteRoomTag
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: |-
+            The id of the user to remove a tag for. The access token must be
+            authorized to make requests for this user ID.
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          required: true
+          description: The ID of the room to remove a tag from.
+          example: "!726s6s6q:example.com"
+          schema:
+            type: string
+        - in: path
+          name: tag
+          required: true
+          description: The tag to remove.
+          example: u.work
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The tag was successfully removed.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+      tags:
+        - User data
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/data/matrix-spec/api/client-server/third_party_lookup.yaml

@@ -0,0 +1,324 @@
+# Copyright 2018 New Vector Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Third-party Lookup API
+  version: 1.0.0
+paths:
+  /thirdparty/protocols:
+    get:
+      summary: Retrieve metadata about all protocols that a homeserver supports.
+      description: |-
+        Fetches the overall metadata about protocols supported by the
+        homeserver. Includes both the available protocols and all fields
+        required for queries against each protocol.
+      operationId: getProtocols
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The protocols supported by the homeserver.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: Dictionary of supported third-party protocols.
+                additionalProperties:
+                  $ref: definitions/protocol.yaml
+                example: {
+                  "irc": {
+                    "user_fields": ["network", "nickname"],
+                    "location_fields": ["network", "channel"],
+                    "icon": "mxc://example.org/aBcDeFgH",
+                    "field_types": {
+                      "network": {
+                        "regexp": "([a-z0-9]+\\.)*[a-z0-9]+",
+                        "placeholder": "irc.example.org"
+                      },
+                      "nickname": {
+                        "regexp": "[^\\s]+",
+                        "placeholder": "username"
+                      },
+                      "channel": {
+                        "regexp": "#[^\\s]+",
+                        "placeholder": "#foobar"
+                      }
+                    },
+                    "instances": [
+                      {
+                        "network_id": "freenode",
+                        "desc": "Freenode",
+                        "icon": "mxc://example.org/JkLmNoPq",
+                        "instance_id": "irc-freenode",
+                        "fields": {
+                          "network": "freenode.net"
+                        }
+                      }
+                    ]
+                  },
+                  "gitter": {
+                    "user_fields": ["username"],
+                    "location_fields": ["room"],
+                    "field_types": {
+                      "username": {
+                        "regexp": "@[^\\s]+",
+                        "placeholder": "@username"
+                      },
+                      "room": {
+                        "regexp": "[^\\s]+\\/[^\\s]+",
+                        "placeholder": "matrix-org/matrix-spec"
+                      }
+                    },
+                    "instances": [
+                      {
+                        "network_id": "gitter",
+                        "desc": "Gitter",
+                        "icon": "mxc://example.org/zXyWvUt",
+                        "instance_id": "gitter-gitter",
+                        "fields": {}
+                      }
+                    ]
+                  }
+                }
+      tags:
+        - Third-party Lookup
+  "/thirdparty/protocol/{protocol}":
+    get:
+      summary: Retrieve metadata about a specific protocol that the homeserver supports.
+      description: Fetches the metadata from the homeserver about a particular
+        third-party protocol.
+      operationId: getProtocolMetadata
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: protocol
+          description: The name of the protocol.
+          required: true
+          example: irc
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The protocol was found and metadata returned.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/protocol.yaml
+        "404":
+          description: The protocol is unknown.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND"
+                  }
+      tags:
+        - Third-party Lookup
+  "/thirdparty/location/{protocol}":
+    get:
+      summary: Retrieve Matrix-side portals rooms leading to a third-party location.
+      description: |-
+        Requesting this endpoint with a valid protocol name results in a list
+        of successful mapping results in a JSON array. Each result contains
+        objects to represent the Matrix room or rooms that represent a portal
+        to this third-party network. Each has the Matrix room alias string,
+        an identifier for the particular third-party network protocol, and an
+        object containing the network-specific fields that comprise this
+        identifier. It should attempt to canonicalise the identifier as much
+        as reasonably possible given the network type.
+      operationId: queryLocationByProtocol
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: protocol
+          description: The protocol used to communicate to the third-party network.
+          required: true
+          example: irc
+          schema:
+            type: string
+        - in: query
+          name: fields
+          description: |-
+            One or more custom fields to help identify the third-party
+            location.
+          schema:
+            type: object
+            additionalProperties:
+              type: string
+      responses:
+        "200":
+          description: At least one portal room was found.
+          content:
+            application/json:
+              schema:
+                $ref: ../application-service/definitions/location_batch.yaml
+        "404":
+          description: No portal rooms were found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND"
+                  }
+      tags:
+        - Third-party Lookup
+  "/thirdparty/user/{protocol}":
+    get:
+      summary: Retrieve the Matrix User ID of a corresponding third-party user.
+      description: |-
+        Retrieve a Matrix User ID linked to a user on the third-party service, given
+        a set of user parameters.
+      operationId: queryUserByProtocol
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: protocol
+          description: The name of the protocol.
+          required: true
+          example: irc
+          schema:
+            type: string
+        - in: query
+          name: fields
+          description: One or more custom fields that are passed to the AS to help
+            identify the user.
+          schema:
+            type: object
+            additionalProperties:
+              type: string
+      responses:
+        "200":
+          description: The Matrix User IDs found with the given parameters.
+          content:
+            application/json:
+              schema:
+                $ref: ../application-service/definitions/user_batch.yaml
+        "404":
+          description: The Matrix User ID was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND"
+                  }
+      tags:
+        - Third-party Lookup
+  /thirdparty/location:
+    get:
+      summary: Reverse-lookup third-party locations given a Matrix room alias.
+      description: |-
+        Retrieve an array of third-party network locations from a Matrix room
+        alias.
+      operationId: queryLocationByAlias
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: alias
+          description: The Matrix room alias to look up.
+          required: true
+          example: "#matrix:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: All found third-party locations.
+          content:
+            application/json:
+              schema:
+                $ref: ../application-service/definitions/location_batch.yaml
+        "404":
+          description: The Matrix room alias was not found
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND"
+                  }
+      tags:
+        - Third-party Lookup
+  /thirdparty/user:
+    get:
+      summary: Reverse-lookup third-party users given a Matrix User ID.
+      description: Retrieve an array of third-party users from a Matrix User ID.
+      operationId: queryUserByID
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: userid
+          description: The Matrix User ID to look up.
+          required: true
+          example: "@bob:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: An array of third-party users.
+          content:
+            application/json:
+              schema:
+                $ref: ../application-service/definitions/user_batch.yaml
+        "404":
+          description: The Matrix User ID was not found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND"
+                  }
+      tags:
+        - Third-party Lookup
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

data/data/matrix-spec/api/client-server/third_party_membership.yaml

@@ -0,0 +1,139 @@
+# Copyright 2016 OpenMarket Ltd
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Room Membership API for third-party identifiers
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/invite":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API does not require that the inviter know the Matrix
+        identifier of the invitee, and instead relies on third-party identifiers.
+        The homeserver uses an identity server to perform the mapping from
+        third-party identifier to a Matrix identifier. The other is documented in the*
+        [joining rooms section](/client-server-api/#post_matrixclientv3roomsroomidinvite).
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the identity server did know the Matrix user identifier for the
+        third-party identifier, the homeserver will append a `m.room.member`
+        event to the room.
+
+        If the identity server does not know a Matrix user identifier for the
+        passed third-party identifier, the homeserver will issue an invitation
+        which can be accepted upon providing proof of ownership of the third-
+        party identifier. This is achieved by the identity server generating a
+        token, which it gives to the inviting homeserver. The homeserver will
+        add an `m.room.third_party_invite` event into the graph for the room,
+        containing that token.
+
+        When the invitee binds the invited third-party identifier to a Matrix
+        user ID, the identity server will give the user a list of pending
+        invitations, each containing:
+
+        - The room ID to which they were invited
+
+        - The token given to the homeserver
+
+        - A signature of the token, signed with the identity server's private key
+
+        - The matrix user ID who invited them to the room
+      operationId: inviteBy3PID
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          example: "!d41d8cd:matrix.org"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              $ref: definitions/invite_3pid.yaml
+        required: true
+      responses:
+        "200":
+          description: The user has been invited to join the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
+          description: |-
+            You do not have permission to invite the user to the room. A
+            meaningful `errcode` and description error text will be returned.
+            Example reasons for rejections are:
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - The inviter is not currently in the room.
+            - The inviter's power level is insufficient to invite users to the room.
+
+            {{% added-in v="1.18"%}} The `M_INVITE_BLOCKED` error code is used to
+            indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "@cheeky_monkey:matrix.org is banned from the room"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Room membership
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer