async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,167 @@
+# 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 Threads List API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/threads":
+    get:
+      x-addedInMatrixVersion: "1.4"
+      summary: Fetches a list of the threads in a room.
+      description: |-
+        This API is used to paginate through the list of the thread roots in a given room. 
+
+        Optionally, the returned list may be filtered according to whether the requesting
+        user has participated in the thread.
+      operationId: getThreadRoots
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID where the thread roots are located.
+          required: true
+          example: "!room:example.org"
+          schema:
+            type: string
+        - in: query
+          name: include
+          description: |-
+            Optional (default `all`) flag to denote which thread roots are of interest to the caller.
+            When `all`, all thread roots found in the room are returned. When `participated`, only
+            thread roots for threads the user has [participated in](/client-server-api/#server-side-aggregation-of-mthread-relationships)
+            will be returned.
+          example: all
+          schema:
+            type: string
+            enum:
+              - all
+              - participated
+        - in: query
+          name: limit
+          description: |-
+            Optional limit for the maximum number of thread roots to include per response. Must be an integer
+            greater than zero.
+
+            Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
+          example: 20
+          schema:
+            type: integer
+        - in: query
+          name: from
+          description: |-
+            A pagination token from a previous result. When not provided, the server starts paginating from
+            the most recent event visible to the user (as per history visibility rules; topologically).
+          example: next_batch_token
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A portion of the available thread roots in the room, based on the
+            filter criteria.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  chunk:
+                    type: array
+                    description: |-
+                      The thread roots, ordered by the `latest_event` in each event's aggregated children. All events
+                      returned include bundled [aggregations](/client-server-api/#aggregations-of-child-events).
+
+                      If the thread root event was sent by an [ignored user](/client-server-api/#ignoring-users), the
+                      event is returned redacted to the caller. This is to simulate the same behaviour of a client doing
+                      aggregation locally on the thread.
+                    items:
+                      $ref: definitions/client_event.yaml
+                  next_batch:
+                    type: string
+                    description: |-
+                      A token to supply to `from` to keep paginating the responses. Not present when there are
+                      no further results.
+                required:
+                  - chunk
+              examples:
+                response:
+                  value: {
+                    "chunk": [
+                      {
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      }
+                    ],
+                    "next_batch": "next_batch_token"
+                  }
+        "400":
+          description: |-
+            The request was invalid in some way. A meaningful `errcode`
+            and description error text will be returned. Example reasons for rejection are:
+
+            - The `from` token is unknown to the server.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "Unknown pagination token"
+                  }
+        "403":
+          description: |-
+            The user cannot view or peek 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 peeking.
+            - The user has been banned from the room.
+            - The room does not exist.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You are not allowed to view this room."
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Threads
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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

@@ -0,0 +1,104 @@
+# 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 Send-to-device API
+  version: 1.0.0
+paths:
+  "/sendToDevice/{eventType}/{txnId}":
+    put:
+      summary: Send an event to a given set of devices.
+      description: |-
+        This endpoint is used to send send-to-device events to a set of
+        client devices.
+      operationId: sendToDevice
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: eventType
+          description: The type of event to send.
+          required: true
+          example: m.new_device
+          schema:
+            type: string
+        - in: path
+          name: txnId
+          description: |-
+            The [transaction ID](/client-server-api/#transaction-identifiers) for this event. Clients should generate an
+            ID unique across requests with the same access token; it will be
+            used by the server to ensure idempotency of requests.
+          required: true
+          example: "35"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              title: body
+              properties:
+                messages:
+                  type: object
+                  description: |-
+                    The messages to send. A map from user ID, to a map from
+                    device ID to message body. The device ID may also be `*`,
+                    meaning all known devices for the user.
+                  patternProperties:
+                    "^@":
+                      x-pattern-format: mx-user-id
+                      type: object
+                      additionalProperties:
+                        type: object
+                        title: EventContent
+                        description: Message content
+                  example:
+                    "@alice:example.com":
+                      TLLBEANAAG:
+                        example_content_key: value
+              required:
+                - messages
+        required: true
+      responses:
+        "200":
+          description: The message was successfully sent.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+      tags:
+        - Send-to-Device messaging
+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/typing.yaml

@@ -0,0 +1,103 @@
+# 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 Typing API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/typing/{userId}":
+    put:
+      summary: Informs the server that the user has started or stopped typing.
+      description: |-
+        This tells the server that the user is typing for the next N
+        milliseconds where N is the value specified in the `timeout` key.
+        Alternatively, if `typing` is `false`, it tells the server that the
+        user has stopped typing.
+      operationId: setTyping
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user who has started to type.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+        - in: path
+          name: roomId
+          description: The room in which the user is typing.
+          required: true
+          example: "!wefh3sfukhs:example.com"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "typing": true,
+                "timeout": 30000
+              }
+              properties:
+                typing:
+                  type: boolean
+                  description: |-
+                    Whether the user is typing or not. If `false`, the `timeout`
+                    key can be omitted.
+                timeout:
+                  type: integer
+                  description: The length of time in milliseconds to mark this user as typing.
+              required:
+                - typing
+        description: The current typing state.
+        required: true
+      responses:
+        "200":
+          description: The new typing state was set.
+          content:
+            application/json:
+              schema:
+                type: object  # empty json object
+              examples:
+                response:
+                  value: {}
+        "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/users.yaml

@@ -0,0 +1,136 @@
+# Copyright 2017 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 User Directory API
+  version: 1.0.0
+paths:
+  /user_directory/search:
+    post:
+      summary: Searches the user directory.
+      description: |-
+        Performs a search for users. The homeserver may determine which
+        subset of users are searched. However, the homeserver MUST at a
+        minimum consider users who are visible to the requester based
+        on their membership in rooms known to the homeserver. This means:
+
+        -   users that share a room with the requesting user
+        -   users who are joined to rooms known to the homeserver that have a
+            `public` [join rule](#mroomjoin_rules)
+        -   users who are joined to rooms known to the homeserver that have a
+            `world_readable` [history visibility](#room-history-visibility)
+        
+        The search MUST consider local users to the homeserver, and SHOULD
+        query remote users as part of the search.
+
+        The search is performed case-insensitively on user IDs and display
+        names preferably using a collation determined based upon the
+        `Accept-Language` header provided in the request, if present.
+      operationId: searchUserDirectory
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              properties:
+                search_term:
+                  type: string
+                  description: The term to search for
+                  example: foo
+                limit:
+                  type: integer
+                  description: The maximum number of results to return. Defaults to 10.
+                  example: 10
+              required:
+                - search_term
+        required: true
+      responses:
+        "200":
+          description: The results of the search.
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - results
+                  - limited
+                properties:
+                  results:
+                    type: array
+                    description: Ordered by rank and then whether or not profile info is available.
+                    items:
+                      title: User
+                      type: object
+                      required:
+                        - user_id
+                      properties:
+                        user_id:
+                          type: string
+                          example: "@foo:bar.com"
+                          description: The user's matrix user ID.
+                        display_name:
+                          type: string
+                          example: Foo
+                          description: The display name of the user, if one exists.
+                        avatar_url:
+                          type: string
+                          format: uri
+                          example: mxc://bar.com/foo
+                          description: The avatar url, as an [`mxc://`
+                            URI](/client-server-api/#matrix-content-mxc-uris),
+                            if one exists.
+                  limited:
+                    type: boolean
+                    description: Indicates if the result list has been truncated by the limit.
+              examples:
+                response:
+                  value: {
+                    "results": [
+                      {
+                        "user_id": "@foo:bar.com",
+                        "display_name": "Foo",
+                        "avatar_url": "mxc://bar.com/foo"
+                      }
+                    ],
+                    "limited": false
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - User directory
+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/versions.yaml

@@ -0,0 +1,108 @@
+# 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 Versions API
+  version: 1.0.0
+paths:
+  /versions:
+    get:
+      summary: Gets the versions of the specification supported by the server.
+      description: |-
+        Gets the versions of the specification supported by the server.
+
+        Values will take the form `vX.Y` or `rX.Y.Z` in historical cases. See
+        [the Specification Versioning](../#specification-versions) for more
+        information.
+
+        The server may additionally advertise experimental features it supports
+        through `unstable_features`. These features should be namespaced and
+        may optionally include version information within their name if desired.
+        Features listed here are not for optionally toggling parts of the Matrix
+        specification and should only be used to advertise support for a feature
+        which has not yet landed in the spec. For example, a feature currently
+        undergoing the proposal process may appear here and eventually be taken
+        off this list once the feature lands in the spec and the server deems it
+        reasonable to do so. Servers can choose to enable some features only for
+        some users, so clients should include authentication in the request to
+        get all the features available for the logged-in user. If no
+        authentication is provided, the server should only return the features
+        available to all users. Servers may wish to keep advertising features
+        here after they've been released into the spec to give clients a chance
+        to upgrade appropriately. Additionally, clients should avoid using
+        unstable features in their stable releases.
+      operationId: getVersions
+      security:
+        - {}
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      x-changedInMatrixVersion:
+        "1.10": |
+          This endpoint can behave differently when authentication is provided.
+      responses:
+        "200":
+          description: The versions supported by the server.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  versions:
+                    type: array
+                    description: The supported versions.
+                    items:
+                      type: string
+                      description: The supported versions
+                  unstable_features:
+                    type: object
+                    description: |-
+                      Experimental features the server supports. Features not listed here,
+                      or the lack of this property all together, indicate that a feature is
+                      not supported.
+                    additionalProperties:
+                      type: boolean
+                      description: Whether or not the namespaced feature is supported.
+                required:
+                  - versions
+              examples:
+                response:
+                  value: {
+                    "versions": [
+                      "r0.0.1",
+                      "v1.1"
+                    ],
+                    "unstable_features": {
+                      "org.example.my_feature": true
+                    }
+                  }
+      tags:
+        - Server administration
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer