async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,152 @@
+# Copyright 2021 The Matrix.org Foundation C.I.C.
+#
+# 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 Knocking API
+  version: 1.0.0
+paths:
+  "/knock/{roomIdOrAlias}":
+    post:
+      x-addedInMatrixVersion: "1.1"
+      summary: Knock on a room, requesting permission to join.
+      description: |-
+        *Note that this API takes either a room ID or alias, unlike other membership APIs.*
+
+        This API "knocks" on the room to ask for permission to join, if the user
+        is allowed to knock on the room. Acceptance of the knock happens out of
+        band from this API, meaning that the client will have to watch for updates
+        regarding the acceptance/rejection of the knock.
+
+        If the room history settings allow, the user will still be able to see
+        history of the room while being in the "knock" state. The user will have
+        to accept the invitation to join the room (acceptance of knock) to see
+        messages reliably. See the `/join` endpoints for more information about
+        history visibility to the user.
+
+        The knock will appear as an entry in the response of the
+        [`/sync`](/client-server-api/#get_matrixclientv3sync) API.
+      operationId: knockRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomIdOrAlias
+          description: The room identifier or alias to knock upon.
+          required: true
+          example: "#monkeys:matrix.org"
+          schema:
+            type: string
+        - in: query
+          name: via
+          x-addedInMatrixVersion: "1.12"
+          description: |-
+            The servers to attempt to knock on the room through. One of the servers
+            must be participating in the room.
+          example:
+            - matrix.org
+            - elsewhere.ca
+          schema:
+            type: array
+            items:
+              type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                reason:
+                  type: string
+                  description: |-
+                    Optional reason to be included as the `reason` on the subsequent
+                    membership event.
+                  example: Looking for support
+        required: true
+      responses:
+        "200":
+          description: |-
+            The room has been knocked upon.
+
+            The knocked room ID must be returned in the `room_id` field.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  room_id:
+                    type: string
+                    description: The knocked room ID.
+                required:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "room_id": "!d41d8cd:matrix.org"
+                  }
+        "403":
+          description: |-
+            You do not have permission to knock on the room. A meaningful `errcode`
+            and description error text will be returned. Example reasons for rejection are:
+
+            - The room is not set up for knocking.
+            - The user has been banned from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to knock on this room."
+                  }
+        "404":
+          description: The room could not be found or resolved to a room ID.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "That room does not appear to exist."
+                  }
+        "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

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

@@ -0,0 +1,163 @@
+# 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 Leaving API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/leave":
+    post:
+      summary: Stop the requesting user participating in a particular room.
+      x-changedInMatrixVersion:
+        "1.18": |-
+          Servers may additionally forget the room provided that they make this behavior
+          transparent.
+      description: |-
+        This API stops a user participating in a particular room.
+
+        If the user was already in the room, they will no longer be able to see
+        new events in the room. If the room requires an invite to join, they
+        will need to be re-invited before they can re-join.
+
+        If the user was invited to the room, but had not joined, this call
+        serves to reject the invite.
+
+        Servers MAY additionally forget the room when this endpoint is called –
+        just as if the user had also invoked [`/forget`](/client-server-api/#post_matrixclientv3roomsroomidforget).
+        Servers that do this, MUST inform clients about this behavior using the
+        [`m.forget_forced_upon_leave`](/client-server-api/#mforget_forced_upon_leave-capability)
+        capability.
+
+        If the server doesn't automatically forget the room, the user will still be
+        allowed to retrieve history from the room which they were previously allowed
+        to see.
+      operationId: leaveRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier to leave.
+          required: true
+          example: "!nkl290a:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "Saying farewell - thanks for the support!"
+              }
+              properties:
+                reason:
+                  x-addedInMatrixVersion: "1.1"
+                  type: string
+                  description: |-
+                    Optional reason to be included as the `reason` on the subsequent
+                    membership event.
+        required: true
+      responses:
+        "200":
+          description: The room has been left.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Room membership
+  "/rooms/{roomId}/forget":
+    post:
+      summary: Stop the requesting user remembering about a particular room.
+      description: |-
+        This API stops a user remembering about a particular room.
+
+        In general, history is a first class citizen in Matrix. After this API
+        is called, however, a user will no longer be able to retrieve history
+        for this room. If all users on a homeserver forget a room, the room is
+        eligible for deletion from that homeserver.
+
+        If the user is currently joined to the room, they must leave the room
+        before calling this API.
+      operationId: forgetRoom
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier to forget.
+          required: true
+          example: "!au1ba7o:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The room has been forgotten.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: The user has not left the room
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN",
+                    "error": "User @example:matrix.org is in room !au1ba7o:matrix.org"
+                  }
+        "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

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

@@ -0,0 +1,68 @@
+# Copyright 2017 Michael Telatynski <7t3chguy@gmail.com>
+#
+# 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 Listing API
+  version: 1.0.0
+paths:
+  /joined_rooms:
+    get:
+      summary: Lists the user's current rooms.
+      description: This API returns a list of the user's current rooms.
+      operationId: getJoinedRooms
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: A list of the rooms the user is in.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - joined_rooms
+                properties:
+                  joined_rooms:
+                    type: array
+                    description: The ID of each room in which the user has `joined` membership.
+                    items:
+                      type: string
+              examples:
+                response:
+                  value: {
+                    "joined_rooms": [
+                      "!foo:example.com"
+                    ]
+                  }
+      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

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

@@ -0,0 +1,280 @@
+# 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 Published Room Directory API
+  version: 1.0.0
+paths:
+  "/directory/list/room/{roomId}":
+    get:
+      summary: Gets the visibility of a room in the directory
+      description: |-
+        Gets the visibility of a given room in the server's
+        published room directory.
+      operationId: getRoomVisibilityOnDirectory
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID.
+          required: true
+          example: "!curbf:matrix.org"
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The visibility of the room in the directory.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  visibility:
+                    type: string
+                    enum:
+                      - private
+                      - public
+                    description: The visibility of the room in the directory.
+              examples:
+                response:
+                  value: {
+                    "visibility": "public"
+                  }
+        "404":
+          description: The room is not known to the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found"
+                  }
+      tags:
+        - Room discovery
+    put:
+      summary: Sets the visibility of a room in the directory
+      description: |-
+        Sets the visibility of a given room in the server's published room directory.
+
+        Servers MAY implement additional access control checks, for instance,
+        to ensure that a room's visibility can only be changed by the room creator
+        or a server administrator.
+      operationId: setRoomVisibilityOnDirectory
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID.
+          required: true
+          example: "!curbf:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                visibility:
+                  type: string
+                  enum:
+                    - private
+                    - public
+                  description: |-
+                    The new visibility setting for the room.
+                    Defaults to `public`.
+              example: {
+                "visibility": "public"
+              }
+        description: The new visibility for the room in the published room directory.
+        required: true
+      responses:
+        "200":
+          description: The visibility was updated, or no change was needed.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "404":
+          description: The room is not known to the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Room not found"
+                  }
+      tags:
+        - Room discovery
+  /publicRooms:
+    get:
+      summary: Lists a server's published room directory
+      description: |-
+        Lists a server's published room directory.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      operationId: getPublicRooms
+      parameters:
+        - in: query
+          name: limit
+          description: Limit the number of results returned.
+          schema:
+            type: integer
+        - in: query
+          name: since
+          description: |-
+            A pagination token from a previous request, allowing clients to
+            get the next (or previous) batch of rooms.
+            The direction of pagination is specified solely by which token
+            is supplied, rather than via an explicit flag.
+          schema:
+            type: string
+        - in: query
+          name: server
+          description: |-
+            The server to fetch the published room directory from. Defaults
+            to the local server. Case sensitive.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A list of the published rooms on the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/public_rooms_response.yaml
+      tags:
+        - Room discovery
+    post:
+      summary: Lists a server's published room directory with an optional filter
+      description: |-
+        Lists a server's published room directory with an optional filter.
+
+        This API returns paginated responses. The rooms are ordered by the number
+        of joined members, with the largest rooms first.
+      operationId: queryPublicRooms
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: server
+          description: |-
+            The server to fetch the published room directory from. Defaults
+            to the local server. Case sensitive.
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                limit:
+                  type: integer
+                  description: Limit the number of results returned.
+                since:
+                  type: string
+                  description: |-
+                    A pagination token from a previous request, allowing clients
+                    to get the next (or previous) batch of rooms.  The direction
+                    of pagination is specified solely by which token is supplied,
+                    rather than via an explicit flag.
+                filter:
+                  type: object
+                  title: Filter
+                  description: Filter to apply to the results.
+                  properties:
+                    generic_search_term:
+                      type: string
+                      description: |-
+                        An optional string to search for in the room metadata, e.g. name,
+                        topic, canonical alias, etc.
+                    room_types:
+                      type: array
+                      x-addedInMatrixVersion: "1.4"
+                      items:
+                        type: ["string", "null"]
+                      description: |-
+                        An optional list of [room types](/client-server-api/#types) to search
+                        for. To include rooms without a room type, specify `null` within this
+                        list. When not specified, all applicable rooms (regardless of type)
+                        are returned.
+                include_all_networks:
+                  type: boolean
+                  description: |-
+                    Whether or not to include all known networks/protocols from
+                    application services on the homeserver. Defaults to `false`.
+                  example: false
+                third_party_instance_id:
+                  type: string
+                  description: |-
+                    The specific third-party network/protocol to request from the
+                    homeserver. Can only be used if `include_all_networks` is false.
+
+                    This is the `instance_id` of a `Protocol Instance` returned by
+                    [`GET /_matrix/client/v3/thirdparty/protocols`](/client-server-api/#get_matrixclientv3thirdpartyprotocols).
+                  example: irc
+              example: {
+                "limit": 10,
+                "filter": {
+                  "generic_search_term": "foo",
+                  "room_types": [
+                    null,
+                    "m.space"
+                  ]
+                },
+                "include_all_networks": false,
+                "third_party_instance_id": "irc-freenode"
+              }
+        description: Options for which rooms to return.
+        required: true
+      responses:
+        "200":
+          description: A filtered list of the published rooms on the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/public_rooms_response.yaml
+      tags:
+        - Room discovery
+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