async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,103 @@
+# Copyright 2018 New Vector Ltd
+# Copyright 2022 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 Read Marker API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/read_markers":
+    post:
+      summary: Set the position of the read marker for a room.
+      description: |-
+        Sets the position of the read marker for a given room, and optionally
+        the read receipt's location.
+      operationId: setReadMarker
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID to set the read marker in for the user.
+          required: true
+          example: "!somewhere:example.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                m.fully_read:
+                  type: string
+                  description: |-
+                    The event ID the read marker should be located at. The
+                    event MUST belong to the room.
+                  example: $somewhere:example.org
+                  x-changedInMatrixVersion:
+                    "1.4": |
+                      This property is no longer required.
+                m.read:
+                  type: string
+                  description: |-
+                    The event ID to set the read receipt location at. This is
+                    equivalent to calling `/receipt/m.read/$elsewhere:example.org`
+                    and is provided here to save that extra call.
+                  example: $elsewhere:example.org
+                m.read.private:
+                  x-addedInMatrixVersion: "1.4"
+                  type: string
+                  description: |-
+                    The event ID to set the *private* read receipt location at. This
+                    equivalent to calling `/receipt/m.read.private/$elsewhere:example.org`
+                    and is provided here to save that extra call.
+                  example: $elsewhere:example.org
+        description: The read marker and optional read receipt locations.
+        required: true
+      responses:
+        "200":
+          description: The read marker, and read receipt(s) if provided, have been updated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties: {}
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Read Markers
+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/receipts.yaml

@@ -0,0 +1,139 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2022 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 Receipts API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/receipt/{receiptType}/{eventId}":
+    post:
+      summary: Send a receipt for the given event ID.
+      description: |-
+        This API updates the marker for the given receipt type to the event ID
+        specified.
+      operationId: postReceipt
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room in which to send the event.
+          required: true
+          example: "!wefuh21ffskfuh345:example.com"
+          schema:
+            type: string
+        - in: path
+          name: receiptType
+          description: |-
+            The type of receipt to send. This can also be `m.fully_read` as an
+            alternative to [`/read_markers`](/client-server-api/#post_matrixclientv3roomsroomidread_markers).
+
+            Note that `m.fully_read` does not appear under `m.receipt`: this endpoint
+            effectively calls `/read_markers` internally when presented with a receipt
+            type of `m.fully_read`.
+          required: true
+          x-changedInMatrixVersion:
+            "1.4": |
+              Allow `m.read.private` receipts and `m.fully_read` markers to be set.
+          example: m.read
+          schema:
+            type: string
+            enum:
+              - m.read
+              - m.read.private
+              - m.fully_read
+        - in: path
+          name: eventId
+          description: The event ID to acknowledge up to.
+          required: true
+          example: $1924376522eioj:example.com
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                thread_id:
+                  type: string
+                  x-addedInMatrixVersion: "1.4"
+                  description: |-
+                    The root thread event's ID (or `main`) for which
+                    thread this receipt is intended to be under. If
+                    not specified, the read receipt is *unthreaded*
+                    (default).
+              example: {
+                "thread_id": "main"
+              }
+        description: |-
+          Extra receipt information to attach to `content` if any. The
+          server will automatically set the `ts` field.
+        required: true
+      responses:
+        "200":
+          description: The receipt was sent.
+          content:
+            application/json:
+              schema:
+                type: object
+                maxProperties: 0  # empty json object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |-
+            The `thread_id` is invalid in some way. For example:
+            * It is not a string.
+            * It is empty.
+            * It is provided for an incompatible receipt type.
+            * The `event_id` is not related to the `thread_id`.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "thread_id field must be a non-empty string"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Room participation
+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/redaction.yaml

@@ -0,0 +1,116 @@
+# 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 message redaction API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/redact/{eventId}/{txnId}":
+    put:
+      summary: Strips all non-integrity-critical information out of an event.
+      description: |-
+        Strips all information out of an event which isn't critical to the
+        integrity of the server-side representation of the room.
+
+        This cannot be undone.
+
+        Any user with a power level greater than or equal to the `m.room.redaction`
+        event power level may send redactions for their own events in the room. If
+        the user's power level is also greater than or equal to the `redact` power
+        level of the room, the user may redact events sent by other users.
+
+        Server administrators may redact events sent by users on their server.
+      operationId: redactEvent
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room from which to redact the event.
+          required: true
+          example: "!637q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: path
+          name: eventId
+          description: The ID of the event to redact.
+          required: true
+          example: $bai2b1i9:matrix.org
+          schema:
+            type: string
+            format: mx-event-id
+            pattern: "^\\$"
+        - in: path
+          name: txnId
+          description: |-
+            The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate a
+            unique ID; it will be used by the server to ensure idempotency of requests.
+          required: true
+          example: "37"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "reason": "Indecent material"
+              }
+              properties:
+                reason:
+                  type: string
+                  description: The reason for the event being redacted.
+        required: true
+      responses:
+        "200":
+          description: An ID for the redaction event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  event_id:
+                    type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
+                    description: A unique identifier for the event.
+              examples:
+                response:
+                  value: {
+                    "event_id": "$YUwQidLecu:example.com"
+                  }
+      tags:
+        - Room participation
+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/refresh.yaml

@@ -0,0 +1,119 @@
+# Copyright 2022 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 Registration and Login API
+  version: 1.0.0
+paths:
+  /refresh:
+    post:
+      x-addedInMatrixVersion: "1.3"
+      summary: Refresh an access token
+      description: |-
+        Refresh an access token. Clients should use the returned access token
+        when making subsequent API calls, and store the returned refresh token
+        (if given) in order to refresh the new access token when necessary.
+
+        After an access token has been refreshed, a server can choose to
+        invalidate the old access token immediately, or can choose not to, for
+        example if the access token would expire soon anyways. Clients should
+        not make any assumptions about the old access token still being valid,
+        and should use the newly provided access token instead.
+
+        The old refresh token remains valid until the new access token or refresh token
+        is used, at which point the old refresh token is revoked.
+
+        Note that this endpoint does not require authentication via an
+        access token. Authentication is provided via the refresh token.
+
+        Application Service identity assertion is disabled for this endpoint.
+      operationId: refresh
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "refresh_token": "some_token"
+              }
+              properties:
+                refresh_token:
+                  type: string
+                  description: The refresh token
+              required:
+                - refresh_token
+        required: true
+      responses:
+        "200":
+          description: A new access token and refresh token were generated.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  access_token:
+                    type: string
+                    description: The new access token to use.
+                  refresh_token:
+                    type: string
+                    description: |-
+                      The new refresh token to use when the access token needs to
+                      be refreshed again. If not given, the old refresh token can
+                      be re-used.
+                  expires_in_ms:
+                    type: integer
+                    description: |-
+                      The lifetime of the access token, in milliseconds. If not
+                      given, the client can assume that the access token will not
+                      expire.
+                required:
+                  - access_token
+              examples:
+                response:
+                  value: {
+                    "access_token": "a_new_token",
+                    "expires_in_ms": 60000,
+                    "refresh_token": "another_new_token"
+                  }
+        "401":
+          description: The provided token was unknown, or has already been used.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_UNKNOWN_TOKEN",
+                    "error": "Soft logged out",
+                    "soft_logout": true
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v3