async-matrix 0.1.3 → 1.1.0

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

@@ -0,0 +1,385 @@
+# 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 Search API
+  version: 1.0.0
+paths:
+  /search:
+    post:
+      summary: Perform a server-side search.
+      description: Performs a full text search across different categories.
+      operationId: search
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: next_batch
+          description: |-
+            The point to return events from. If given, this should be a
+            `next_batch` result from a previous call to this endpoint.
+          example: YWxsCgpOb25lLDM1ODcwOA
+          schema:
+            type: string
+      requestBody:
+        content:
+          application/json:
+            schema:
+              type: object
+              example: {
+                "search_categories": {
+                  "room_events": {
+                    "keys": [
+                      "content.body"
+                    ],
+                    "search_term": "martians and men",
+                    "order_by": "recent",
+                    "groupings": {
+                      "group_by": [
+                        {
+                          "key": "room_id"
+                        }
+                      ]
+                    }
+                  }
+                }
+              }
+              properties:
+                search_categories:
+                  type: object
+                  title: Categories
+                  description: Describes which categories to search in and their criteria.
+                  properties:
+                    room_events:
+                      type: object
+                      title: Room Events Criteria
+                      description: Mapping of category name to search criteria.
+                      properties:
+                        search_term:
+                          type: string
+                          description: The string to search events for
+                        keys:
+                          type: array
+                          items:
+                            type: string
+                            enum:
+                              - content.body
+                              - content.name
+                              - content.topic
+                          description: The keys to search. Defaults to all.
+                        filter:
+                          type: object
+                          title: Filter
+                          description: This takes a [filter](/client-server-api/#filtering).
+                          allOf:
+                            - $ref: definitions/room_event_filter.yaml
+                        order_by:
+                          title: Ordering
+                          type: string
+                          enum:
+                            - recent
+                            - rank
+                          description: |-
+                            The order in which to search for results.
+                            By default, this is `"rank"`.
+                        event_context:
+                          title: Include Event Context
+                          type: object
+                          description: |-
+                            Configures whether any context for the events
+                            returned are included in the response.
+                          properties:
+                            before_limit:
+                              type: integer
+                              title: Before limit
+                              description: |-
+                                How many events before the result are
+                                returned. By default, this is `5`.
+                            after_limit:
+                              type: integer
+                              title: After limit
+                              description: |-
+                                How many events after the result are
+                                returned. By default, this is `5`.
+                            include_profile:
+                              type: boolean
+                              title: Return profile information
+                              description: |-
+                                Requests that the server returns the
+                                historic profile information for the users
+                                that sent the events that were returned.
+                                By default, this is `false`.
+                        include_state:
+                          type: boolean
+                          title: Include current state
+                          description: |-
+                            Requests the server return the current state for
+                            each room returned.
+                        groupings:
+                          type: object
+                          title: Groupings
+                          description: |-
+                            Requests that the server partitions the result set
+                            based on the provided list of keys.
+                          properties:
+                            group_by:
+                              type: array
+                              title: Groups
+                              description: List of groups to request.
+                              items:
+                                type: object
+                                title: Group
+                                description: Configuration for group.
+                                properties:
+                                  key:
+                                    type: string
+                                    title: Group Key
+                                    description: Key that defines the group.
+                                    enum:
+                                      - room_id
+                                      - sender
+                      required:
+                        - search_term
+              required:
+                - search_categories
+        required: true
+      responses:
+        "200":
+          description: Results of the search.
+          content:
+            application/json:
+              schema:
+                type: object
+                title: Results
+                required:
+                  - search_categories
+                properties:
+                  search_categories:
+                    type: object
+                    title: Result Categories
+                    description: Describes which categories to search in and their criteria.
+                    properties:
+                      room_events:
+                        type: object
+                        title: Result Room Events
+                        description: Mapping of category name to search criteria.
+                        properties:
+                          count:
+                            type: integer
+                            description: An approximate count of the total number of results found.
+                          highlights:
+                            type: array
+                            title: Highlights
+                            description: List of words which should be highlighted, useful for stemming
+                              which may change the query terms.
+                            items:
+                              type: string
+                          results:
+                            type: array
+                            title: Results
+                            description: List of results in the requested order.
+                            items:
+                              type: object
+                              title: Result
+                              description: The result object.
+                              properties:
+                                rank:
+                                  type: number
+                                  description: A number that describes how closely this result matches the search.
+                                    Higher is closer.
+                                result:
+                                  type: object
+                                  title: Event
+                                  description: The event that matched.
+                                  allOf:
+                                    - $ref: definitions/client_event.yaml
+                                context:
+                                  type: object
+                                  title: Event Context
+                                  description: Context for result, if requested.
+                                  properties:
+                                    start:
+                                      type: string
+                                      title: Start Token
+                                      description: Pagination token for the start of the chunk
+                                    end:
+                                      type: string
+                                      title: End Token
+                                      description: Pagination token for the end of the chunk
+                                    profile_info:
+                                      type: object
+                                      title: Profile Information
+                                      description: |-
+                                        The historic profile information of the
+                                        users that sent the events returned.
+
+                                        The key is the user ID for which
+                                        the profile belongs to.
+                                      patternProperties:
+                                        "^@":
+                                          x-pattern-format: mx-user-id
+                                          type: object
+                                          title: User Profile
+                                          properties:
+                                            displayname:
+                                              type: string
+                                              title: Display name
+                                            avatar_url:
+                                              type: string
+                                              format: uri
+                                              title: Avatar Url
+                                    events_before:
+                                      type: array
+                                      title: Events Before
+                                      description: Events just before the result.
+                                      items:
+                                        title: Event
+                                        type: object
+                                        $ref: definitions/client_event.yaml
+                                    events_after:
+                                      type: array
+                                      title: Events After
+                                      description: Events just after the result.
+                                      items:
+                                        title: Event
+                                        type: object
+                                        $ref: definitions/client_event.yaml
+                          state:
+                            type: object
+                            title: Current state
+                            description: |-
+                              The current state for every room in the results.
+                              This is included if the request had the
+                              `include_state` key set with a value of `true`.
+
+                              The key is the room ID for which the `State
+                              Event` array belongs to.
+                            patternProperties:
+                              "^!":
+                                x-pattern-format: mx-room-id
+                                type: array
+                                title: Room State
+                                items:
+                                  $ref: definitions/client_event.yaml
+                          groups:
+                            type: object
+                            title: Groups
+                            description: |-
+                              Any groups that were requested.
+
+                              The outer `string` key is the group key requested (eg: `room_id`
+                              or `sender`). The inner `string` key is the grouped value (eg:
+                              a room's ID or a user's ID).
+                            additionalProperties:
+                              type: object
+                              title: Group Key
+                              description: The results for a given group.
+                              additionalProperties:
+                                type: object
+                                title: Group Value
+                                description: The results for a particular group value.
+                                properties:
+                                  next_batch:
+                                    type: string
+                                    title: Next Batch in Group
+                                    description: |-
+                                      Token that can be used to get the next batch
+                                      of results in the group, by passing as the
+                                      `next_batch` parameter to the next call. If
+                                      this field is absent, there are no more
+                                      results in this group.
+                                  order:
+                                    type: integer
+                                    title: Group Order
+                                    description: |-
+                                      Key that can be used to order different
+                                      groups.
+                                  results:
+                                    type: array
+                                    description: Which results are in this group.
+                                    items:
+                                      type: string
+                                      title: Result Event ID
+                          next_batch:
+                            type: string
+                            title: Next Batch
+                            description: |-
+                              Token that can be used to get the next batch of
+                              results, by passing as the `next_batch` parameter to
+                              the next call. If this field is absent, there are no
+                              more results.
+              examples:
+                response:
+                  value: {
+                    "search_categories": {
+                      "room_events": {
+                        "groups": {
+                          "room_id": {
+                            "!qPewotXpIctQySfjSy:localhost": {
+                              "order": 1,
+                              "next_batch": "BdgFsdfHSf-dsFD",
+                              "results": [
+                                "$144429830826TWwbB:localhost"
+                              ]
+                            }
+                          }
+                        },
+                        "highlights": [
+                          "martians",
+                          "men"
+                        ],
+                        "next_batch": "5FdgFsd234dfgsdfFD",
+                        "count": 1224,
+                        "results": [
+                          {
+                            "rank": 0.00424866,
+                            "result": {
+                              "room_id": "!qPewotXpIctQySfjSy:localhost",
+                              "event_id": "$144429830826TWwbB:localhost",
+                              "$ref": "../../event-schemas/examples/m.room.message$m.text.yaml"
+                            }
+                          }
+                        ]
+                      }
+                    }
+                  }
+        "400":
+          description: Part of the request was invalid.
+        "429":
+          description: This request was rate-limited.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/rate_limited.yaml
+      tags:
+        - Search
+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/space_hierarchy.yaml

@@ -0,0 +1,237 @@
+# Copyright 2021 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 Space Hierarchy API
+  version: 1.0.0
+paths:
+  "/rooms/{roomId}/hierarchy":
+    get:
+      x-addedInMatrixVersion: "1.2"
+      summary: Retrieve a portion of a space tree.
+      description: |-
+        Paginates over the space tree in a depth-first manner to locate child rooms of a given space.
+
+        Where a child room is unknown to the local server, federation is used to fill in the details.
+        The servers listed in the `via` array should be contacted to attempt to fill in missing rooms.
+
+        Only [`m.space.child`](/client-server-api/#mspacechild) state events of the room are considered.
+        Invalid child rooms and parent events are not covered by this endpoint.
+      operationId: getSpaceHierarchy
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: path
+          name: roomId
+          description: The room ID of the space to get a hierarchy for.
+          required: true
+          example: "!space:example.org"
+          schema:
+            type: string
+        - in: query
+          name: suggested_only
+          description: |-
+            Optional (default `false`) flag to indicate whether or not the server should only consider
+            suggested rooms. Suggested rooms are annotated in their [`m.space.child`](/client-server-api/#mspacechild)
+            event contents.
+          example: true
+          schema:
+            type: boolean
+        - in: query
+          name: limit
+          description: |-
+            Optional limit for the maximum number of rooms 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: max_depth
+          description: |-
+            Optional limit for how far to go into the space. Must be a non-negative integer.
+
+            When reached, no further child rooms will be returned.
+
+            Servers should apply a default value, and impose a maximum value to avoid resource exhaustion.
+          example: 5
+          schema:
+            type: integer
+        - in: query
+          name: from
+          description: |-
+            A pagination token from a previous result. If specified, `max_depth` and `suggested_only` cannot
+            be changed from the first request.
+          example: next_batch_token
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A portion of the space tree, starting at the provided room ID.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  rooms:
+                    type: array
+                    description: |-
+                       The rooms for the current page, with the current filters.
+
+                       The server should return any rooms where at least one of the following conditions is true:
+                       
+                       * The requesting user is currently a member (their [room membership](#room-membership) is `join`).
+                       * The requesting user already has permission to join, i.e. one of the following:
+                         * The user's room membership is `invite`.
+                         * The room's [join rules](#mroomjoin_rules) are set to `public`.
+                         * The room's join rules are set to [`restricted`](#restricted-rooms), provided the user meets one of the specified conditions.
+                       * The room is "knockable" (the room's join rules are set to `knock`, or `knock_restricted`, in a room version that supports those settings).
+                       * The room's [`m.room.history_visibility`](#room-history-visibility) is set to `world_readable`.
+                    items:
+                      allOf:
+                        - $ref: definitions/room_summary.yaml
+                        - type: object
+                          title: SpaceHierarchyRoomsChunk
+                          properties:
+                            children_state:
+                              type: array
+                              description: |-
+                                The [`m.space.child`](/client-server-api/#mspacechild) events of the space-room, represented
+                                as [Stripped State Events](/client-server-api/#stripped-state) with an added `origin_server_ts` key.
+
+                                If the room is not a space-room, this should be empty.
+                              items:
+                                allOf:
+                                  - $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                  - type: object
+                                    title: StrippedChildStateEvent
+                                    properties:
+                                      origin_server_ts:
+                                        type: integer
+                                        format: int64
+                                        description: The `origin_server_ts` for the event.
+                                    required:
+                                      - origin_server_ts
+                            room_type:
+                              x-addedInMatrixVersion: "1.4" # Extends room_summary.yaml
+                            allowed_room_ids:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            encryption:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                            room_version:
+                              x-addedInMatrixVersion: "1.15" # Extends room_summary.yaml
+                          required:
+                            - children_state
+                  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:
+                  - rooms
+              examples:
+                response:
+                  value: {
+                    "rooms": [
+                      {
+                        "room_id": "!space:example.org",
+                        "avatar_url": "mxc://example.org/abcdef",
+                        "guest_can_join": false,
+                        "name": "The First Space",
+                        "topic": "No other spaces were created first, ever",
+                        "world_readable": true,
+                        "join_rule": "public",
+                        "room_type": "m.space",
+                        "num_joined_members": 42,
+                        "canonical_alias": "#general:example.org",
+                        "children_state": [
+                          {
+                            "type": "m.space.child",
+                            "state_key": "!a:example.org",
+                            "content": {
+                              "via": [
+                                "example.org"
+                              ]
+                            },
+                            "sender": "@alice:example.org",
+                            "origin_server_ts": 1629413349153
+                          }
+                        ]
+                      }
+                    ],
+                    "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.
+            - `suggested_only` or `max_depth` changed during pagination.
+          content:
+            application/json:
+              schema:
+                $ref: definitions/errors/error.yaml
+              examples:
+                response:
+                  value: {
+                    "errcode": "M_INVALID_PARAM",
+                    "error": "suggested_only and max_depth cannot change on paginated requests"
+                  }
+        "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:
+        - Spaces
+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