async-matrix 0.1.3 → 1.0.0

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

@@ -0,0 +1,147 @@
+# 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 events in room by date API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/timestamp_to_event":
+    get:
+      x-addedInMatrixVersion: "1.6"
+      summary: Get the closest event ID to the given timestamp
+      description: |-
+        Get the ID of the event closest to the given timestamp, in the
+        direction specified by the `dir` parameter.
+
+        If the server does not have all of the room history and does not have
+        an event suitably close to the requested timestamp, it can use the
+        corresponding [federation endpoint](/server-server-api/#get_matrixfederationv1timestamp_to_eventroomid)
+        to ask other servers for a suitable event.
+
+        After calling this endpoint, clients can call
+        [`/rooms/{roomId}/context/{eventId}`](/client-server-api/#get_matrixclientv3roomsroomidcontexteventid)
+        to obtain a pagination token to retrieve the events around the returned event.
+
+        The event returned by this endpoint could be an event that the client
+        cannot render, and so may need to paginate in order to locate an event
+        that it can display, which may end up being outside of the client's
+        suitable range.  Clients can employ different strategies to display
+        something reasonable to the user.  For example, the client could try
+        paginating in one direction for a while, while looking at the
+        timestamps of the events that it is paginating through, and if it
+        exceeds a certain difference from the target timestamp, it can try
+        paginating in the opposite direction.  The client could also simply
+        paginate in one direction and inform the user that the closest event
+        found in that direction is outside of the expected range.
+      operationId: getEventByTimestamp
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The ID of the room to search
+          required: true
+          example: "!636q39766251:matrix.org"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: query
+          name: ts
+          description: |-
+            The timestamp to search from, as given in milliseconds
+            since the Unix epoch.
+          required: true
+          example: 1432684800000
+          schema:
+            type: integer
+        - in: query
+          name: dir
+          description: The direction in which to search.  `f` for forwards, `b` for
+            backwards.
+          required: true
+          example: f
+          schema:
+            type: string
+            enum:
+              - f
+              - b
+      responses:
+        "200":
+          description: An event was found matching the search parameters.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  event_id:
+                    type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
+                    description: The ID of the event found
+                  origin_server_ts:
+                    type: integer
+                    description: |-
+                      The event's timestamp, in milliseconds since the Unix epoch.
+                      This makes it easy to do a quick comparison to see if the
+                      `event_id` fetched is too far out of range to be useful for your
+                      use case.
+                required:
+                  - event_id
+                  - origin_server_ts
+              examples:
+                response:
+                  value: {
+                    "event_id": "$143273582443PhrSn:example.org",
+                    "origin_server_ts": 1432735824653
+                  }
+        "404":
+          description: No event was found.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_NOT_FOUND",
+                    "error": "Unable to find event from 1432684800000 in forward direction"
+                  }
+        "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/v1
+components:
+  securitySchemes:
+    accessTokenQuery:
+      $ref: definitions/security.yaml#/accessTokenQuery
+    accessTokenBearer:
+      $ref: definitions/security.yaml#/accessTokenBearer

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

@@ -0,0 +1,188 @@
+openapi: 3.1.0
+info:
+  title: Matrix Client-Server Rooms API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/initialSync":
+    get:
+      summary: Snapshot the current state of a room and its most recent messages.
+      description: |-
+        Get a copy of the current state and the most recent messages in a room.
+
+        This endpoint should now exclusively be used for "peeking" into viewable rooms
+        you're not a member of ([Room Previews](/client-server-api/#room-previews)).
+        Using this endpoint for something other than peeking was deprecated in r0 of this specification.
+        The relevant information for syncing is now returned by the
+        [`/sync`](/client-server-api/#get_matrixclientv3sync) API. See the
+        [migration guide](https://matrix.org/docs/guides/migrating-from-client-server-api-v-1#deprecated-endpoints).
+      operationId: roomInitialSync
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to get the data.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+      responses:
+        "200":
+          description: The current state of the room
+          content:
+            application/json:
+              schema:
+                title: RoomInfo
+                type: object
+                properties:
+                  room_id:
+                    type: string
+                    format: mx-room-id
+                    pattern: "^!"
+                    description: The ID of this room.
+                  membership:
+                    type: string
+                    description: The user's membership state in this room.
+                    enum:
+                      - invite
+                      - join
+                      - leave
+                      - ban
+                  messages:
+                    type: object
+                    title: PaginationChunk
+                    description: The pagination chunk for this room.
+                    properties:
+                      start:
+                        type: string
+                        description: |-
+                          A token which correlates to the start of `chunk`. Can be passed to
+                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
+                          to retrieve earlier events.
+
+                          If no earlier events are available, this property may be omitted from
+                          the response.
+                      end:
+                        type: string
+                        description: |-
+                          A token which correlates to the end of `chunk`. Can be passed to
+                          [`/rooms/<room_id>/messages`](/client-server-api/#get_matrixclientv3roomsroomidmessages)
+                          to retrieve later events.
+                      chunk:
+                        type: array
+                        description: |-
+                          If the user is a member of the room this will be a
+                          list of the most recent messages for this room. If
+                          the user has left the room this will be the
+                          messages that preceded them leaving. This array
+                          will consist of at most `limit` elements.
+                        items:
+                          $ref: definitions/client_event.yaml
+                    required:
+                      - end
+                      - chunk
+                  state:
+                    type: array
+                    description: |-
+                      If the user is a member of the room this will be the
+                      current state of the room as a list of events. If the
+                      user has left the room this will be the state of the
+                      room when they left it.
+                    items:
+                      $ref: definitions/client_event.yaml
+                  visibility:
+                    type: string
+                    enum:
+                      - private
+                      - public
+                    description: |-
+                      Whether this room is visible to the `/publicRooms` API
+                      or not.
+                  account_data:
+                    type: array
+                    description: The private data that this user has attached to this room.
+                    items:
+                      title: Event
+                      type: object
+                      allOf:
+                        - $ref: ../../event-schemas/schema/core-event-schema/event.yaml
+                required:
+                  - room_id
+              examples:
+                response:
+                  value: {
+                    "membership": "join",
+                    "messages": {
+                      "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.message$m.file.yaml"
+                        }
+                      ],
+                      "end": "s3456_9_0",
+                      "start": "t44-3453_9_0"
+                    },
+                    "room_id": "!636q39766251:example.com",
+                    "state": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.join_rules.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.member.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.create.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.power_levels.yaml"
+                      }
+                    ],
+                    "visibility": "private",
+                    "account_data": [
+                      {
+                        "type": "m.tag",
+                        "content": {
+                          "tags": {
+                            "work": {
+                              "order": "1"
+                            }
+                          }
+                        }
+                      }
+                    ]
+                  }
+        "403":
+          description: |
+            You aren't a member of the room and weren't previously a member of the room.
+      tags:
+        - Room participation
+      deprecated: false
+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/room_send.yaml

@@ -0,0 +1,130 @@
+# Copyright 2016 OpenMarket Ltd
+# Copyright 2023 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 message event send API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/send/{eventType}/{txnId}":
+    put:
+      summary: Send a message event to the given room.
+      x-changedInMatrixVersion:
+        "1.18": |-
+          Homeservers must support sending `m.room.redaction` events with this endpoint
+          for all room versions.
+      description: |-
+        This endpoint is used to send a message event to a room. Message events
+        allow access to historical events and pagination, making them suited
+        for "once-off" activity in a room.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
+
+        Homeservers MUST allow clients to send `m.room.redaction` events with this
+        endpoint for all room versions. In rooms with a version older than 11 they
+        MUST move the `redacts` property inside the `content` to the top level of
+        the event.
+      operationId: sendMessage
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to send the event to.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: path
+          name: eventType
+          description: The type of event to send.
+          required: true
+          example: m.room.message
+          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
+              example: {
+                "msgtype": "m.text",
+                "body": "hello"
+              }
+        required: true
+      responses:
+        "200":
+          description: An ID for the sent event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  event_id:
+                    type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
+                    description: A unique identifier for the event.
+                required:
+                  - event_id
+              examples:
+                response:
+                  value: {
+                    "event_id": "$YUwRidLecu:example.com"
+                  }
+        "400":
+          description: |-
+            The request is invalid. A [standard error response](/client-server-api/#standard-error-response)
+            will be returned. As well as the normal common error codes, other reasons for rejection include:
+
+            - `M_DUPLICATE_ANNOTATION`: The request is an attempt to send a [duplicate annotation](/client-server-api/#avoiding-duplicate-annotations).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.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/room_state.yaml

@@ -0,0 +1,159 @@
+# 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 state event send API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/state/{eventType}/{stateKey}":
+    put:
+      summary: Send a state event to the given room.
+      description: |
+        State events can be sent using this endpoint.  These events will be
+        overwritten if `<room id>`, `<event type>` and `<state key>` all
+        match.
+
+        Requests to this endpoint **cannot use transaction IDs**
+        like other `PUT` paths because they cannot be differentiated from the
+        `state_key`. Furthermore, `POST` is unsupported on state paths.
+
+        The body of the request should be the content object of the event; the
+        fields in this object will vary depending on the type of event. See
+        [Room Events](/client-server-api/#room-events) for the `m.` event specification.
+
+        If the event type being sent is `m.room.canonical_alias` servers
+        SHOULD ensure that any new aliases being listed in the event are valid
+        per their grammar/syntax and that they point to the room ID where the
+        state event is to be sent. Servers do not validate aliases which are
+        being removed or are already present in the state event.
+      operationId: setRoomStateWithKey
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to set the state in
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+            format: mx-room-id
+            pattern: "^!"
+        - in: path
+          name: eventType
+          description: The type of event to send.
+          required: true
+          example: m.room.member
+          schema:
+            type: string
+        - in: path
+          name: stateKey
+          description: |-
+            The state_key for the state to send. Defaults to the empty string. When
+            an empty string, the trailing slash on this endpoint is optional.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "membership": "join",
+                "avatar_url": "mxc://localhost/SEsfnsuifSDFSSEF",
+                "displayname": "Alice Margatroid"
+              }
+        required: true
+      responses:
+        "200":
+          description: An ID for the sent event.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  event_id:
+                    type: string
+                    format: mx-event-id
+                    pattern: "^\\$"
+                    description: A unique identifier for the event.
+                required:
+                  - event_id
+              examples:
+                response:
+                  value: {
+                    "event_id": "$YUwRidLecu:example.com"
+                  }
+        "400":
+          description: |-
+            The sender's request is malformed.
+
+            Some example error codes include:
+
+            * `M_INVALID_PARAM`: One or more aliases within the `m.room.canonical_alias`
+              event have invalid syntax.
+
+            * `M_BAD_ALIAS`: One or more aliases within the `m.room.canonical_alias` event
+              do not point to the room ID for which the state event is to be sent to.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_BAD_ALIAS",
+                    "error": "The alias '#hello:example.org' does not point to this room."
+                  }
+        "403":
+          description: |-
+            The sender doesn't have permission to send the event into the room.
+
+            {{% added-in v="1.18"%}} If the `eventType` is `m.room.member` and
+            the `membership` is `invite`, the `M_INVITE_BLOCKED` error code is
+            used to indicate that the homeserver rejected the invite due to
+            [invite blocking](/client-server-api/#invite-permission).
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_FORBIDDEN",
+                    "error": "You do not have permission to send the event."
+                  }
+      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