async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,177 @@
+# 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 Banning API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/ban":
+    post:
+      summary: Ban a user in the room.
+      description: |-
+        Ban a user in the room. If the user is currently in the room, also kick them.
+
+        When a user is banned from a room, they may not join it or be invited to it until they are unbanned.
+
+        The caller must have the required power level in order to perform this operation.
+      operationId: ban
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier (not alias) from which the user should be banned.
+          required: true
+          example: "!e42d8c:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "Telling unfunny jokes",
+                "user_id": "@cheeky_monkey:matrix.org"
+              }
+              properties:
+                user_id:
+                  type: string
+                  description: The fully qualified user ID of the user being banned.
+                reason:
+                  x-addedInMatrixVersion: "1.1"
+                  type: string
+                  description: The reason the user has been banned. This will be supplied as the
+                    `reason` on the target's updated
+                    [`m.room.member`](/client-server-api/#mroommember) event.
+              required:
+                - user_id
+        required: true
+      responses:
+        "200":
+          description: The user has been kicked and banned from the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
+          description: |-
+            You do not have permission to ban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
+
+            - The banner is not currently in the room.
+            - The banner's power level is insufficient to ban users from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have a high enough power level to ban from this room."
+                  }
+      tags:
+        - Room membership
+  "/rooms/{roomId}/unban":
+    post:
+      summary: Unban a user from the room.
+      description: |-
+        Unban a user from the room. This allows them to be invited to the room,
+        and join if they would otherwise be allowed to join according to its join rules.
+
+        The caller must have the required power level in order to perform this operation.
+      operationId: unban
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier (not alias) from which the user should be
+            unbanned.
+          required: true
+          example: "!e42d8c:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "reason": "They've been banned long enough"
+              }
+              properties:
+                user_id:
+                  type: string
+                  description: The fully qualified user ID of the user being unbanned.
+                reason:
+                  x-addedInMatrixVersion: "1.1"
+                  type: string
+                  description: |-
+                    Optional reason to be included as the `reason` on the subsequent
+                    membership event.
+              required:
+                - user_id
+        required: true
+      responses:
+        "200":
+          description: The user has been unbanned from the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "403":
+          description: |-
+            You do not have permission to unban the user from the room. A meaningful `errcode` and description error text will be returned. Example reasons for rejections are:
+
+            - The unbanner's power level is insufficient to unban users from the room.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have a high enough power level to unban from this room."
+                  }
+      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/capabilities.yaml

@@ -0,0 +1,235 @@
+# Copyright 2019 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 Capabilities API
+  version: 1.0.0
+paths:
+  /capabilities:
+    get:
+      summary: Gets information about the server's capabilities.
+      description: |-
+        Gets information about the server's supported feature set
+        and other relevant capabilities.
+      operationId: getCapabilities
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      responses:
+        "200":
+          description: The capabilities of the server.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - capabilities
+                properties:
+                  capabilities:
+                    type: object
+                    title: Capabilities
+                    description: |-
+                      The custom capabilities the server supports, using the
+                      Java package naming convention.
+                    additionalProperties:
+                      description: |-
+                        Application-dependent keys using the
+                        [Common Namespaced Identifier Grammar](/appendices/#common-namespaced-identifier-grammar).
+                    properties:
+                      m.change_password:
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: Capability to indicate if the user can change their password.
+                      m.forget_forced_upon_leave:
+                        x-addedInMatrixVersion: "1.18"
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: |-
+                          Capability to indicate if the server automatically forgets rooms once the user
+                          leaves.
+                      m.room_versions:
+                        type: object
+                        description: The room versions the server supports.
+                        title: RoomVersionsCapability
+                        properties:
+                          default:
+                            type: string
+                            description: The default room version the server is using for new rooms.
+                            example: "1"
+                          available:
+                            type: object
+                            description: A detailed description of the room versions the server supports.
+                            additionalProperties:
+                              type: string
+                              title: RoomVersionStability
+                              enum:
+                                - stable
+                                - unstable
+                              description: The stability of the room version.
+                        required:
+                          - default
+                          - available
+                      m.set_displayname:
+                        deprecated: true
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their display name.
+                          Refer to `m.profile_fields` for extended profile management.
+
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `displayname` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
+                      m.set_avatar_url:
+                        deprecated: true
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: |
+                          **Deprecated:** Capability to indicate if the user can change their avatar.
+                          Refer to `m.profile_fields` for extended profile management.
+
+                          For backwards compatibility, servers that directly or indirectly include the
+                          `avatar_url` profile field in the `m.profile_fields` capability MUST also
+                          set this capability accordingly.
+                      m.3pid_changes:
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: Capability to indicate if the user can change 3PID associations
+                          on their account.
+                      m.get_login_token:
+                        $ref: '#/components/schemas/booleanCapability'
+                        description: Capability to indicate if the user can generate tokens to log further
+                          clients into their account.
+                      m.profile_fields:
+                        x-addedInMatrixVersion: "1.16"
+                        type: object
+                        title: ProfileFieldsCapability
+                        description: Capability to indicate if the user can set or modify extended profile fields via
+                          [`PUT /_matrix/client/v3/profile/{userId}/{keyName}`](/client-server-api/#put_matrixclientv3profileuseridkeyname).
+                          If absent, clients SHOULD assume custom profile fields are supported, provided the
+                          homeserver advertises a specification version that includes `m.profile_fields` in the
+                          [`/versions`](/client-server-api/#get_matrixclientversions) response.
+                        properties:
+                          allowed:
+                            type: array
+                            description: |
+                              If present, a list of profile fields that clients are allowed to create, modify or delete,
+                              provided `enabled` is `true`; no other profile fields may be changed.
+
+                              If absent, clients may set all profile fields except those forbidden by the `disallowed`
+                              list, where present.
+                            items:
+                              type: string
+                            example:
+                              - "m.example_field"
+                              - "org.example.job_title"
+                          disallowed:
+                            type: array
+                            description:  |
+                              This property has no meaning if `allowed` is also specified.
+
+                              Otherwise, if present, a list of profile fields that clients are _not_ allowed to create, modify or delete.
+                              Provided `enabled` is `true`, clients MAY assume that they can set any profile field which is not
+                              included in this list.
+                            items:
+                              type: string
+                            example:
+                              - "org.example.managed_field"
+                          enabled:
+                            type: boolean
+                            description: "`true` if the user can create, update or delete any profile fields, `false` otherwise."
+                            example: true
+                        required:
+                          - enabled
+                      m.account_moderation:
+                        x-addedInMatrixVersion: "1.18"
+                        type: object
+                        title: AccountModerationCapability
+                        description: |-
+                          Capability to indicate if the user can perform account moderation actions
+                          via [server administration](/client-server-api/#server-administration)
+                          endpoints.
+
+                          This property should be omitted altogether if `suspend` and `lock` would
+                          be `false`.
+                        properties:
+                          suspend:
+                            type: boolean
+                            description: |-
+                              `true` if the user can suspend a user via [`PUT /admin/suspend/{userId}`](/client-server-api/#put_matrixclientv1adminsuspenduserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
+                          lock:
+                            type: boolean
+                            description: |-
+                              `true` if the user can lock a user via [`PUT /admin/lock/{userId}`](/client-server-api/#put_matrixclientv1adminlockuserid),
+                              `false` otherwise.
+
+                              Defaults to `false`.
+                            example: true
+              examples:
+                response:
+                  value: {
+                    "capabilities": {
+                      "m.change_password": {
+                        "enabled": false
+                      },
+                      "m.room_versions": {
+                        "default": "1",
+                        "available": {
+                          "1": "stable",
+                          "2": "stable",
+                          "3": "unstable",
+                          "test-version": "unstable"
+                        }
+                      },
+                      "com.example.custom.ratelimit": {
+                        "max_requests_per_hour": 600
+                      }
+                    }
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Capabilities
+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
+  schemas:
+    booleanCapability:
+      type: object
+      title: BooleanCapability
+      properties:
+        enabled:
+          type: boolean
+          description: True if the user can perform the action, false otherwise.
+          example: false
+      required:
+        - enabled