async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,161 @@
+# 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 Event Context API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/context/{eventId}":
+    get:
+      summary: Get events and state around the specified event.
+      description: |-
+        This API returns a number of events that happened just before and
+        after the specified event. This allows clients to get the context
+        surrounding an event.
+
+        *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: getEventContext
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room to get events from.
+          required: true
+          example: "!636q39766251:example.com"
+          schema:
+            type: string
+        - in: path
+          name: eventId
+          description: The event to get context around.
+          required: true
+          example: $f3h4d129462ha:example.com
+          schema:
+            type: string
+        - in: query
+          name: limit
+          description: |-
+            The maximum number of context events to return. The limit applies
+            to the sum of the `events_before` and `events_after` arrays. The
+            requested event ID is always returned in `event` even if `limit` is
+            0. Defaults to 10.
+          example: 3
+          schema:
+            type: integer
+        - in: query
+          name: filter
+          description: |-
+            A JSON `RoomEventFilter` to filter the returned events with. The
+            filter is only applied to `events_before`, `events_after`, and
+            `state`. It is not applied to the `event` itself. The filter may
+            be applied before or/and after the `limit` parameter - whichever the
+            homeserver prefers.
+
+            See [Filtering](/client-server-api/#filtering) for more information.
+          example: 66696p746572
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The events and state surrounding the requested event.
+          content:
+            application/json:
+              schema:
+                type: object
+                description: The events and state surrounding the requested event.
+                properties:
+                  start:
+                    type: string
+                    description: A token that can be used to paginate backwards with.
+                  end:
+                    type: string
+                    description: A token that can be used to paginate forwards with.
+                  events_before:
+                    type: array
+                    description: |-
+                      A list of room events that happened just before the
+                      requested event, in reverse-chronological order.
+                    items:
+                      $ref: definitions/client_event.yaml
+                  event:
+                    description: Details of the requested event.
+                    allOf:
+                      - $ref: definitions/client_event.yaml
+                  events_after:
+                    type: array
+                    description: |-
+                      A list of room events that happened just after the
+                      requested event, in chronological order.
+                    items:
+                      $ref: definitions/client_event.yaml
+                  state:
+                    type: array
+                    description: The state of the room at the last event returned.
+                    items:
+                      $ref: definitions/client_event.yaml
+              examples:
+                response:
+                  value: {
+                    "end": "t29-57_2_0_2",
+                    "events_after": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                      }
+                    ],
+                    "event": {
+                      "event_id": "$f3h4d129462ha:example.com",
+                      "room_id": "!636q39766251:example.com",
+                      "$ref": "../../event-schemas/examples/m.room.message$m.image.yaml"
+                    },
+                    "events_before": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.message$m.file.yaml"
+                      }
+                    ],
+                    "start": "t27-54_2_0_2",
+                    "state": [
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.create.yaml"
+                      },
+                      {
+                        "room_id": "!636q39766251:example.com",
+                        "$ref": "../../event-schemas/examples/m.room.member.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/filter.yaml

@@ -0,0 +1,224 @@
+# 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 filter API
+  version: 1.0.0
+paths:
+  "/user/{userId}/filter":
+    post:
+      summary: Upload a new filter.
+      description: |-
+        Uploads a new filter definition to the homeserver.
+        Returns a filter ID that may be used in future requests to
+        restrict which events are returned to the client.
+      operationId: defineFilter
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          required: true
+          description: The id of the user uploading the filter. The access token must be
+            authorized to make requests for this user id.
+          example: "@alice:example.com"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              allOf:
+                - $ref: definitions/sync_filter.yaml
+              example: {
+                "room": {
+                  "state": {
+                    "types": [
+                      "m.room.*"
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ]
+                  },
+                  "timeline": {
+                    "limit": 10,
+                    "types": [
+                      "m.room.message"
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ],
+                    "not_senders": [
+                      "@spam:example.com"
+                    ]
+                  },
+                  "ephemeral": {
+                    "types": [
+                      "m.receipt",
+                      "m.typing"
+                    ],
+                    "not_rooms": [
+                      "!726s6s6q:example.com"
+                    ],
+                    "not_senders": [
+                      "@spam:example.com"
+                    ]
+                  }
+                },
+                "presence": {
+                  "types": [
+                    "m.presence"
+                  ],
+                  "not_senders": [
+                    "@alice:example.com"
+                  ]
+                },
+                "event_format": "client",
+                "event_fields": [
+                  "type",
+                  "content",
+                  "sender"
+                ]
+              }
+        description: The filter to upload.
+        required: true
+      responses:
+        "200":
+          description: The filter was created.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  filter_id:
+                    type: string
+                    description: |-
+                      The ID of the filter that was created. Cannot start
+                      with a `{` as this character is used to determine
+                      if the filter provided is inline JSON or a previously
+                      declared filter by homeservers on some APIs.
+                    example: 66696p746572
+                required:
+                  - filter_id
+      tags:
+        - Room participation
+  "/user/{userId}/filter/{filterId}":
+    get:
+      summary: Download a filter
+      operationId: getFilter
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: userId
+          description: The user ID to download a filter for.
+          required: true
+          example: "@alice:example.com"
+          schema:
+            type: string
+            format: mx-user-id
+            pattern: "^@"
+        - in: path
+          name: filterId
+          description: The filter ID to download.
+          required: true
+          example: 66696p746572
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The filter definition.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/sync_filter.yaml
+              examples:
+                response:
+                  value: {
+                    "room": {
+                      "state": {
+                        "types": [
+                          "m.room.*"
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ]
+                      },
+                      "timeline": {
+                        "limit": 10,
+                        "types": [
+                          "m.room.message"
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ],
+                        "not_senders": [
+                          "@spam:example.com"
+                        ]
+                      },
+                      "ephemeral": {
+                        "types": [
+                          "m.receipt",
+                          "m.typing"
+                        ],
+                        "not_rooms": [
+                          "!726s6s6q:example.com"
+                        ],
+                        "not_senders": [
+                          "@spam:example.com"
+                        ]
+                      }
+                    },
+                    "presence": {
+                      "types": [
+                        "m.presence"
+                      ],
+                      "not_senders": [
+                        "@alice:example.com"
+                      ]
+                    },
+                    "event_format": "client",
+                    "event_fields": [
+                      "type",
+                      "content",
+                      "sender"
+                    ]
+                  }
+        "404":
+          description: Unknown filter.
+      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/inviting.yaml

@@ -0,0 +1,149 @@
+# 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 Joining API
+  version: 1.0.0
+paths:
+  # With an extra " " to disambiguate from the 3pid invite endpoint
+  # The extra space makes it sort first for what I'm sure is a good reason.
+  "/rooms/{roomId}/invite ":
+    post:
+      summary: Invite a user to participate in a particular room.
+      description: |-
+        *Note that there are two forms of this API, which are documented separately.
+        This version of the API requires that the inviter knows the Matrix
+        identifier of the invitee. The other is documented in the
+        [third-party invites](/client-server-api/#third-party-invites) section.*
+
+        This API invites a user to participate in a particular room.
+        They do not start participating in the room until they actually join the
+        room.
+
+        Only users currently in a particular room can invite other users to
+        join that room.
+
+        If the user was invited to the room, the homeserver will append a
+        `m.room.member` event to the room.
+      operationId: inviteUser
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room identifier (not alias) to which to invite the user.
+          required: true
+          example: "!d41d8cd:matrix.org"
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "user_id": "@cheeky_monkey:matrix.org",
+                "reason": "Welcome to the team!"
+              }
+              properties:
+                user_id:
+                  type: string
+                  description: The fully qualified user ID of the invitee.
+                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 invited to join the room, or was already invited
+            to the room.
+          content:
+            application/json:
+              schema:
+                type: object
+              examples:
+                response:
+                  value: {}
+        "400":
+          description: |-
+
+            The request is invalid. A meaningful `errcode` and description
+            error text will be returned. Example reasons for rejection include:
+
+            - The request body is malformed (`errcode` set to `M_BAD_JSON`
+              or `M_NOT_JSON`).
+
+            - One or more users being invited to the room are residents of a
+              homeserver which does not support the requested room version. The
+              `errcode` will be `M_UNSUPPORTED_ROOM_VERSION` in these cases.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+        "403":
+          description: |-
+            You do not have permission to invite the user to the room. A
+            meaningful `errcode` and description error text will be returned.
+            Example reasons for rejections are:
+
+            - The invitee has been banned from the room.
+            - The invitee is already a member of the room.
+            - The inviter is not currently in the room.
+            - The inviter's power level is insufficient to invite users to the room.
+
+            {{% added-in v="1.18"%}} 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": "@cheeky_monkey:matrix.org is banned from the room"
+                  }
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      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