async-matrix 0.1.3 → 1.1.0

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

@@ -0,0 +1,194 @@
+# 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 Rooms API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/messages":
+    get:
+      summary: Get a list of events for this room
+      description: |-
+        This API returns a list of message and state events for a room. It uses
+        pagination query parameters to paginate history in the room.
+
+        *Note*: This endpoint supports lazy-loading of room member events. See
+        [Lazy-loading room members](/client-server-api/#lazy-loading-room-members) for more information.
+      operationId: getRoomEvents
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to get events from.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: query
+          name: from
+          x-changedInMatrixVersion:
+            "1.3": |
+              Previously, this field was required and paginating from the first or
+              last visible event in the room history wasn't supported.
+          description: |-
+            The token to start returning events from. This token can be obtained
+            from a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
+            or from an `end` token returned by a previous request to this endpoint.
+
+            This endpoint can also accept a value returned as a `start` token
+            by a previous request to this endpoint, though servers are not
+            required to support this. Clients should not rely on the behaviour.
+
+            If it is not provided, the homeserver shall return a list of messages
+            from the first or last (per the value of the `dir` parameter) visible
+            event in the room history for the requesting user.
+          required: false
+          example: s345_678_333
+          schema:
+            type: string
+        - in: query
+          name: to
+          description: |-
+            The token to stop returning events at. This token can be obtained from
+            a `prev_batch` or `next_batch` token returned by the `/sync` endpoint,
+            or from an `end` token returned by a previous request to this endpoint.
+          required: false
+          schema:
+            type: string
+        - in: query
+          name: dir
+          description: |-
+            The direction to return events from. If this is set to `f`, events
+            will be returned in chronological order starting at `from`. If it
+            is set to `b`, events will be returned in *reverse* chronological
+            order, again starting at `from`.
+          required: true
+          example: b
+          schema:
+            type: string
+            enum:
+              - b
+              - f
+        - in: query
+          name: limit
+          description: "The maximum number of events to return. Default: 10."
+          example: 3
+          schema:
+            type: integer
+        - in: query
+          name: filter
+          description: A JSON RoomEventFilter to filter returned events with.
+          example: '{"contains_url":true}'
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A list of messages with a new token to request more.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: A list of messages with a new token to request more.
+                properties:
+                  start:
+                    type: string
+                    description: |-
+                      A token corresponding to the start of `chunk`. This will be the same as
+                      the value given in `from`.
+                  end:
+                    type: string
+                    description: |-
+                      A token corresponding to the end of `chunk`. This token can be passed
+                      back to this endpoint to request further events.
+
+                      If no further events are available (either because we have
+                      reached the start of the timeline, or because the user does
+                      not have permission to see any more events), this property
+                      is omitted from the response.
+                  chunk:
+                    type: array
+                    description: |-
+                      A list of room events. The order depends on the `dir` parameter.
+                      For `dir=b` events will be in reverse-chronological order,
+                      for `dir=f` in chronological order. (The exact definition of `chronological`
+                      is dependent on the server implementation.)
+
+                      Note that an empty `chunk` does not *necessarily* imply that no more events
+                      are available. Clients should continue to paginate until no `end` property
+                      is returned.
+                    items:
+                      $ref: definitions/client_event.yaml
+                  state:
+                    type: array
+                    description: |-
+                      A list of state events relevant to showing the `chunk`. For example, if
+                      `lazy_load_members` is enabled in the filter then this may contain
+                      the membership events for the senders of events in the `chunk`.
+
+                      Unless `include_redundant_members` is `true`, the server
+                      may remove membership events which would have already been
+                      sent to the client in prior calls to this endpoint, assuming
+                      the membership of those members has not changed.
+                    items:
+                      $ref: definitions/client_event.yaml
+                required:
+                  - start
+                  - chunk
+              examples:
+                response:
+                  value: {
+                    "start": "t47429-4392820_219380_26003_2265",
+                    "end": "t47409-4357353_219380_26003_2265",
+                    "chunk": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.name.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.video.yaml"
+                      }
+                    ]
+                  }
+        "403":
+          description: |
+            You aren't a member of the room.
+      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/notifications.yaml

@@ -0,0 +1,152 @@
+# 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 Notifications API
+  version: 1.0.0
+paths:
+  /notifications:
+    get:
+      summary: Gets a list of events that the user has been notified about
+      description: |-
+        This API is used to paginate through the list of events that the
+        user has been, or would have been notified about.
+      operationId: getNotifications
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: from
+          description: |-
+            Pagination token to continue from. This should be the `next_token`
+            returned from an earlier call to this endpoint.
+          required: false
+          example: xxxxx
+          schema:
+            type: string
+        - in: query
+          name: limit
+          description: Limit on the number of events to return in this request.
+          required: false
+          example: 20
+          schema:
+            type: integer
+        - in: query
+          name: only
+          description: |-
+            Allows basic filtering of events returned. Supply `highlight`
+            to return only events where the notification had the highlight
+            tweak set.
+          required: false
+          example: highlight
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A batch of events is being returned
+          content:
+            application/json:
+              schema:
+                type: object
+                required:
+                  - notifications
+                properties:
+                  next_token:
+                    type: string
+                    description: |-
+                      The token to supply in the `from` param of the next
+                      `/notifications` request in order to request more
+                      events. If this is absent, there are no more results.
+                  notifications:
+                    type: array
+                    items:
+                      type: object
+                      required:
+                        - actions
+                        - event
+                        - read
+                        - room_id
+                        - ts
+                      title: Notification
+                      properties:
+                        actions:
+                          type: array
+                          description: |-
+                            The action(s) to perform when the conditions for this rule are met.
+                            See [Push Rules: API](/client-server-api/#push-rules-api).
+                          items:
+                            type: ["object", "string"]
+                        event:
+                          title: Event
+                          description: The Event object for the event that triggered the notification.
+                          allOf:
+                            - $ref: definitions/client_event_without_room_id.yaml
+                        profile_tag:
+                          type: string
+                          description: The profile tag of the rule that matched this event.
+                        read:
+                          type: boolean
+                          description: |-
+                            Indicates whether the user has sent a read receipt indicating
+                            that they have read this message.
+                        room_id:
+                          type: string
+                          description: The ID of the room in which the event was posted.
+                        ts:
+                          type: integer
+                          format: int64
+                          description: |-
+                            The unix timestamp at which the event notification was sent,
+                            in milliseconds.
+                    description: The list of events that triggered notifications.
+              examples:
+                response:
+                  value: {
+                    "next_token": "abcdef",
+                    "notifications": [
+                      {
+                        "actions": [
+                          "notify"
+                        ],
+                        "profile_tag": "hcbvkzxhcvb",
+                        "read": true,
+                        "room_id": "!abcdefg:example.com",
+                        "ts": 1475508881945,
+                        "event": {
+                          "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                        }
+                      }
+                    ]
+                  }
+      tags:
+        - Push notifications
+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/oauth_server_metadata.yaml

@@ -0,0 +1,238 @@
+# Copyright 2025 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 OAuth 2.0 Server Metadata Discovery API
+  version: 1.0.0
+paths:
+  "/auth_metadata":
+    get:
+      summary: Get the OAuth 2.0 authorization server metadata.
+      description: |-
+        Gets the OAuth 2.0 authorization server metadata, as defined in
+        [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414), including the
+        endpoint URLs and the supported parameters that can be used by the
+        clients.
+
+        This endpoint definition includes only the fields that are meaningful in
+        the context of the Matrix specification. The full list of possible
+        fields is available in the [OAuth Authorization Server Metadata
+        registry](https://www.iana.org/assignments/oauth-parameters/oauth-parameters.xhtml#authorization-server-metadata),
+        and normative definitions of them are available in their respective
+        RFCs.
+
+        {{% boxes/note %}}
+        The authorization server metadata is relatively large and may change
+        over time. Clients should:
+
+        - Cache the metadata appropriately based on HTTP caching headers
+        - Refetch the metadata if it is stale
+        {{% /boxes/note %}}
+      operationId: getAuthMetadata
+      responses:
+        "200":
+          description: The OAuth 2.0 authorization server metadata.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  issuer:
+                    type: string
+                    format: uri
+                    description: |-
+                      The authorization server's issuer identifier, which is a URL that uses the
+                      `https` scheme and has no query or fragment components.
+
+                      This is not used in the context of the Matrix specification, but is required
+                      by [RFC 8414](https://datatracker.ietf.org/doc/html/rfc8414).
+                  authorization_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the authorization endpoint, necessary to use the authorization code
+                      grant.
+                  token_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the token endpoint, used by the grants.
+                  revocation_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the revocation endpoint, necessary to log out a client by invalidating
+                      its access and refresh tokens.
+                  registration_endpoint:
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the client registration endpoint, necessary to perform dynamic
+                      registration of a client.
+                  response_types_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 response type strings that the server supports at the
+                      authorization endpoint.
+
+                      This array MUST contain at least the `code` value, for clients to be able to
+                      use the authorization code grant.
+                    items:
+                      type: string
+                      description: A response type that the server supports.
+                  grant_types_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 grant type strings that the server supports at the token
+                      endpoint.
+
+                      This array MUST contain at least the `authorization_code` and `refresh_token`
+                      values, for clients to be able to use the authorization code grant and refresh
+                      token grant, respectively.
+
+                      {{% added-in v="1.18" %}} It MAY also contain
+                      `urn:ietf:params:oauth:grant-type:device_code` to indicate support for the
+                      [device authorization grant](/client-server-api/#device-authorization-grant).
+                    items:
+                      type: string
+                      description: A grant type that the server supports.
+                  response_modes_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 response mode strings that the server supports at the
+                      authorization endpoint.
+
+                      This array MUST contain at least the `query` and `fragment` values, for
+                      improved security in the authorization code grant.
+                    items:
+                      type: string
+                      description: A response mode that the server supports.
+                  code_challenge_methods_supported:
+                    type: array
+                    description: |-
+                      List of OAuth 2.0 Proof Key for Code Exchange (PKCE) code challenge methods
+                      that the server supports at the authorization endpoint.
+
+                      This array MUST contain at least the `S256` value, for improved security in
+                      the authorization code grant.
+                    items:
+                      type: string
+                      description: A PKCE code challenge method that the server supports.
+                  prompt_values_supported:
+                    type: array
+                    description: |-
+                      List of OpenID Connect prompt values that the server supports at the
+                      authorization endpoint.
+
+                      Only the `create` value defined in [Initiating User Registration via OpenID
+                      Connect](https://openid.net/specs/openid-connect-prompt-create-1_0.html) is
+                      supported, for a client to signal to the server that the user desires to
+                      register a new account.
+                    items:
+                      type: string
+                      description: A prompt value that the server supports.
+                  account_management_uri:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      The URL where the user is able to access the account management capabilities
+                      of the homeserver.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                  account_management_actions_supported:
+                    x-addedInMatrixVersion: "1.18"
+                    type: array
+                    description: |-
+                      List of actions that the account management URL supports.
+
+                      This is an extension [defined in this specification](/client-server-api/#oauth-20-account-management).
+                    items:
+                      type: string
+                      enum:
+                        - "org.matrix.profile"
+                        - "org.matrix.devices_list"
+                        - "org.matrix.device_view"
+                        - "org.matrix.device_delete"
+                        - "org.matrix.account_deactivate"
+                        - "org.matrix.cross_signing_reset"
+                      description: An action that the account management URL supports.
+                  device_authorization_endpoint:
+                    x-addedInMatrixVersion: "1.18"
+                    type: string
+                    format: uri
+                    description: |-
+                      URL of the device authorization endpoint, as defined in
+                      [RFC 8628](https://datatracker.ietf.org/doc/html/rfc8628), necessary to use
+                      the [device authorization grant](/client-server-api/#device-authorization-grant).
+                required:
+                  - issuer
+                  - authorization_endpoint
+                  - token_endpoint
+                  - revocation_endpoint
+                  - registration_endpoint
+                  - response_types_supported
+                  - grant_types_supported
+                  - response_modes_supported
+                  - code_challenge_methods_supported
+                example: {
+                  "issuer": "https://account.example.com/",
+                  "authorization_endpoint": "https://account.example.com/oauth2/auth",
+                  "token_endpoint": "https://account.example.com/oauth2/token",
+                  "registration_endpoint": "https://account.example.com/oauth2/clients/register",
+                  "device_authorization_endpoint": "https://account.example.com/oauth2/device",
+                  "revocation_endpoint": "https://account.example.com/oauth2/revoke",
+                  "response_types_supported": ["code"],
+                  "grant_types_supported": ["authorization_code", "refresh_token", "urn:ietf:params:oauth:grant-type:device_code"],
+                  "response_modes_supported": ["query", "fragment"],
+                  "code_challenge_methods_supported": ["S256"],
+                  "account_management_uri": "https://account.example.com/manage",
+                  "account_management_actions_supported": [
+                    "org.matrix.profile",
+                    "org.matrix.devices_list",
+                    "org.matrix.device_view",
+                    "org.matrix.device_delete",
+                    "org.matrix.account_deactivate",
+                    "org.matrix.cross_signing_reset",
+                  ],
+                }
+        "404":
+          description: |-
+            With `M_UNRECOGNIZED`: the homeserver does not support the OAuth 2.0 API.
+            (See [Authentication API discovery](/client-server-api/#authentication-api-discovery).)
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value:
+                    {
+                      "errcode": "M_UNRECOGNIZED",
+                      "error": "Legacy authentication is in use on this homeserver.",
+                    }
+      tags:
+        - Session management
+servers:
+  - url: "{protocol}://{hostname}{basePath}"
+    variables:
+      protocol:
+        enum:
+          - http
+          - https
+        default: https
+      hostname:
+        default: localhost:8008
+      basePath:
+        default: /_matrix/client/v1