async-matrix 0.1.2 → 1.0.0

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

@@ -0,0 +1,692 @@
+# Copyright 2016, 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 sync API
+  version: 1.0.0
+paths:
+  /sync:
+    get:
+      summary: Synchronise the client's state and receive new messages.
+      description: |-
+        Synchronise the client's state with the latest state on the server.
+        Clients use this API when they first log in to get an initial snapshot
+        of the state on the server, and then continue to call this API to get
+        incremental deltas to the state, and to receive new messages.
+
+        *Note*: This endpoint supports lazy-loading. See [Filtering](/client-server-api/#filtering)
+        for more information. Lazy-loading members is only supported on the `state` part of a
+        [`RoomFilter`](#post_matrixclientv3useruseridfilter_request_roomfilter)
+        for this endpoint. When lazy-loading is enabled, servers MUST include the
+        syncing user's own membership event when they join a room, or when the
+        full state of rooms is requested, to aid discovering the user's avatar &
+        displayname.
+
+        Further, like other members, the user's own membership event is eligible
+        for being considered redundant by the server. When a sync is `limited`,
+        the server MUST return membership events for events in the gap
+        (between `since` and the start of the returned timeline), regardless
+        as to whether or not they are redundant. This ensures that joins/leaves
+        and profile changes which occur during the gap are not lost.
+
+        Note that the default behaviour of `state` is to include all membership
+        events, alongside other state, when lazy-loading is not enabled.
+      operationId: sync
+      security:
+        - accessTokenQuery: []
+        - accessTokenBearer: []
+      parameters:
+        - in: query
+          name: filter
+          description: |-
+            The ID of a filter created using the filter API or a filter JSON
+            object encoded as a string. The server will detect whether it is
+            an ID or a JSON object by whether the first character is a `"{"`
+            open brace. Passing the JSON inline is best suited to one off
+            requests. Creating a filter using the filter API is recommended for
+            clients that reuse the same filter multiple times, for example in
+            long poll requests.
+
+            See [Filtering](/client-server-api/#filtering) for more information.
+          example: 66696p746572
+          schema:
+            type: string
+        - in: query
+          name: since
+          description: |-
+            A point in time to continue a sync from. This should be the
+            `next_batch` token returned by an earlier call to this endpoint.
+          example: s72594_4483_1934
+          schema:
+            type: string
+        - in: query
+          name: full_state
+          description: |-
+            Controls whether to include the full state for all rooms the user
+            is a member of.
+
+            If this is set to `true`, then all state events will be returned,
+            even if `since` is non-empty. The timeline will still be limited
+            by the `since` parameter. In this case, the `timeout` parameter
+            will be ignored and the query will return immediately, possibly with
+            an empty timeline.
+
+            If `false`, and `since` is non-empty, only state which has
+            changed since the point indicated by `since` will be returned.
+
+            By default, this is `false`.
+          example: false
+          schema:
+            type: boolean
+        - in: query
+          name: set_presence
+          description: |-
+            Controls whether the client is automatically marked as online by
+            polling this API. If this parameter is omitted then the client is
+            automatically marked as online when it uses this API. Otherwise if
+            the parameter is set to "offline" then the client is not marked as
+            being online when it uses this API. When set to "unavailable", the
+            client is marked as being idle.
+          example: offline
+          schema:
+            type: string
+            enum:
+              - offline
+              - online
+              - unavailable
+        - in: query
+          name: timeout
+          description: |-
+            The maximum time to wait, in milliseconds, before returning this
+            request. If no events (or other data) become available before this
+            time elapses, the server will return a response with empty fields.
+
+            By default, this is `0`, so the server will return immediately
+            even if the response is empty.
+          example: 30000
+          schema:
+            type: integer
+        - in: query
+          name: use_state_after
+          x-addedInMatrixVersion: "1.16"
+          description: |-
+            Controls whether to receive state changes between the previous sync
+            and the **start** of the timeline, or between the previous sync and
+            the **end** of the timeline.
+
+            If this is set to `true`, servers MUST respond with the state
+            between the previous sync and the **end** of the timeline in
+            `state_after` and MUST omit `state`.
+
+            If `false`, servers MUST respond with the state between the previous
+            sync and the **start** of the timeline in `state` and MUST omit
+            `state_after`.
+
+            Servers MAY implement this parameter ahead of declaring support for
+            the version of the spec in which it was introduced. Consequently,
+            clients MAY set this parameter to `true` regardless of the
+            [`/versions`](/client-server-api/#get_matrixclientversions) response.
+            If they do, they can infer whether the server actually supports this
+            parameter from the presence of `state_after` in the response. If
+            `state_after` is missing, clients MUST behave as if they had not
+            specified the parameter and update their local state with events
+            in `state` and `timeline`.
+
+            By default, this is `false`.
+          example: false
+          schema:
+            type: boolean
+      responses:
+        "200":
+          description: The initial snapshot or delta for the client to use to update their
+            state.
+          content:
+            application/json:
+              schema:
+                type: object
+                properties:
+                  next_batch:
+                    type: string
+                    description: |-
+                      The batch token to supply in the `since` param of the next
+                      `/sync` request.
+                  rooms:
+                    title: Rooms
+                    type: object
+                    description: Updates to rooms.
+                    properties:
+                      join:
+                        title: Joined Rooms
+                        type: object
+                        description: |-
+                          The rooms that the user has joined, mapped as room ID to
+                          room information.
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Joined Room
+                            type: object
+                            properties:
+                              summary:
+                                title: RoomSummary
+                                type: object
+                                description: |-
+                                  Information about the room which clients may need to
+                                  correctly render it to users.
+                                properties:
+                                  m.heroes:
+                                    type: array
+                                    description: |-
+                                      The users which can be used to generate a room name
+                                      if the room does not have one. Required if the room's
+                                      `m.room.name` or `m.room.canonical_alias` state events
+                                      are unset or empty.
+
+                                      This should be the first 5 members of the room, ordered
+                                      by stream ordering, which are joined or invited. The
+                                      list must never include the client's own user ID. When
+                                      no joined or invited members are available, this should
+                                      consist of the banned and left users. More than 5 members
+                                      may be provided, however less than 5 should only be provided
+                                      when there are less than 5 members to represent.
+
+                                      When lazy-loading room members is enabled, the membership
+                                      events for the heroes MUST be included in the `state`,
+                                      unless they are redundant. When the list of users changes,
+                                      the server notifies the client by sending a fresh list of
+                                      heroes. If there are no changes since the last sync, this
+                                      field may be omitted.
+                                    items:
+                                      type: string
+                                      format: mx-user-id
+                                      pattern: "^@"
+                                  m.joined_member_count:
+                                    type: integer
+                                    description: |-
+                                      The number of users with `membership` of `join`,
+                                      including the client's own user ID. If this field has
+                                      not changed since the last sync, it may be omitted.
+                                      Required otherwise.
+                                  m.invited_member_count:
+                                    type: integer
+                                    description: |-
+                                      The number of users with `membership` of `invite`.
+                                      If this field has not changed since the last sync, it
+                                      may be omitted. Required otherwise.
+                              state:
+                                title: State
+                                type: object
+                                description: |-
+                                  Updates to the state, between the time indicated by
+                                  the `since` parameter, and the **start** of the
+                                  `timeline` (or all state up to the **start** of the
+                                  `timeline`, if `since` is not given, or
+                                  `full_state` is true).
+
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
+                                  be incomplete if `lazy_load_members` is enabled in
+                                  the `/sync` filter, and only return the member events
+                                  required to display the senders of the timeline events
+                                  in this response.
+                                  {{% /boxes/note %}}
+
+                                  MUST be omitted if `use_state_after` was set to `true`
+                                  in the request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  Updates to the state, between the time indicated by
+                                  the `since` parameter, and the **end** of the
+                                  `timeline` (or all state up to the **end** of the
+                                  `timeline`, if `since` is not given, or
+                                  `full_state` is true).
+
+                                  {{% boxes/note %}}
+                                  State updates for `m.room.member` events will
+                                  be incomplete if `lazy_load_members` is enabled in
+                                  the `/sync` filter, and only return the member events
+                                  required to display the senders of the timeline events
+                                  in this response.
+                                  {{% /boxes/note %}}
+
+                                  If this field is set, even if it is empty, clients MUST
+                                  only update their local state with events in this list,
+                                  and MUST NOT update their local state with events in
+                                  `timeline`. If this field is not set, clients MUST update
+                                  their local state with events in `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              timeline:
+                                title: Timeline
+                                type: object
+                                description: |-
+                                  The timeline of messages and state changes in the
+                                  room.
+                                allOf:
+                                  - $ref: definitions/timeline_batch.yaml
+                              ephemeral:
+                                title: Ephemeral
+                                type: object
+                                description: |-
+                                  The new ephemeral events in the room (events that
+                                  aren't recorded in the timeline or state of the
+                                  room). In this version of the spec, these are
+                                  [typing notification](/client-server-api/#typing-notifications)
+                                  and [read receipt](/client-server-api/#receipts) events.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
+                              account_data:
+                                title: Account Data
+                                type: object
+                                description: |-
+                                  The private data that this user has attached to
+                                  this room.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
+                              unread_notifications:
+                                title: Unread Notification Counts
+                                type: object
+                                description: |-
+                                  Counts of unread notifications for this room. See the
+                                  [Receiving notifications](/client-server-api/#receiving-notifications) section
+                                  for more information on how these are calculated.
+
+                                  If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                                  these counts will only be for the main timeline rather than all events in the room.
+                                  See the [threading module](/client-server-api/#threading) for more information.
+                                x-changedInMatrixVersion:
+                                  "1.4": |
+                                    Updated to reflect behaviour of having `unread_thread_notifications` as `true` in
+                                    the `RoomEventFilter` for `/sync`.
+                                properties:
+                                  highlight_count:
+                                    title: Highlighted notification count
+                                    type: integer
+                                    description: The number of unread notifications for this room with the highlight
+                                      flag set.
+                                  notification_count:
+                                    title: Total notification count
+                                    type: integer
+                                    description: The total number of unread notifications for this room.
+                              unread_thread_notifications:
+                                title: Unread Thread Notification Counts
+                                type: object
+                                description: |-
+                                  If `unread_thread_notifications` was specified as `true` on the `RoomEventFilter`,
+                                  the notification counts for each [thread](/client-server-api/#threading) in this room.
+                                  The object is keyed by thread root ID, with values matching `unread_notifications`.
+
+                                  If a thread does not have any notifications it can be omitted from this object. If
+                                  no threads have notification counts, this whole object can be omitted.
+                                x-addedInMatrixVersion: "1.4"
+                                patternProperties:
+                                  "^\\$":
+                                    x-pattern-format: mx-event-id
+                                    title: ThreadNotificationCounts
+                                    type: object
+                                    properties:
+                                      highlight_count:
+                                        title: ThreadedHighlightNotificationCount
+                                        type: integer
+                                        description: The number of unread notifications for this *thread* with the
+                                          highlight flag set.
+                                      notification_count:
+                                        title: ThreadedTotalNotificationCount
+                                        type: integer
+                                        description: The total number of unread notifications for this *thread*.
+                      invite:
+                        title: Invited Rooms
+                        type: object
+                        description: |-
+                          The rooms that the user has been invited to, mapped as room ID to
+                          room information.
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Invited Room
+                            type: object
+                            properties:
+                              invite_state:
+                                title: InviteState
+                                type: object
+                                description: |-
+                                  The [stripped state](/client-server-api/#stripped-state) of a room that the user has
+                                  been invited to.
+                                properties:
+                                  events:
+                                    description: |-
+                                      The [stripped state events](/client-server-api/#stripped-state) that form the
+                                      invite state.
+                                    items:
+                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                    type: array
+                      knock:
+                        title: Knocked rooms
+                        type: object
+                        description: The rooms that the user has knocked upon, mapped as room ID to room
+                          information.
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Knocked Room
+                            type: object
+                            properties:
+                              knock_state:
+                                title: KnockState
+                                type: object
+                                description: |-
+                                  The [stripped state](/client-server-api/#stripped-state) of a room that the user has
+                                  knocked upon.
+                                properties:
+                                  events:
+                                    description: |-
+                                      The [stripped state events](/client-server-api/#stripped-state) that form the
+                                      knock state.
+                                    items:
+                                      $ref: ../../event-schemas/schema/core-event-schema/stripped_state.yaml
+                                    type: array
+                      leave:
+                        title: Left rooms
+                        type: object
+                        description: |-
+                          The rooms that the user has left or been banned from, mapped as room ID to
+                          room information.
+                        patternProperties:
+                          "^!":
+                            x-pattern-format: mx-room-id
+                            title: Left Room
+                            type: object
+                            properties:
+                              state:
+                                title: State
+                                type: object
+                                description: |-
+                                  The state updates for the room up to the **start** of the timeline.
+
+                                  MUST be omitted if `use_state_after` was set to `true` in the
+                                  request.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              state_after:
+                                title: State
+                                type: object
+                                x-addedInMatrixVersion: "1.16"
+                                description: |-
+                                  The state updates for the room up to the **end** of the timeline.
+
+                                  If this field is set, even if it is empty, clients MUST only
+                                  update their local state with events in this list, and MUST NOT
+                                  update their local state with events in `timeline`. If this field
+                                  is not set, clients MUST update their local state with events in
+                                  `state` and `timeline`.
+
+                                  **Required** if `use_state_after` was set to `true` in the
+                                  request, even if it is empty.
+                                allOf:
+                                  - $ref: definitions/state_event_batch.yaml
+                              timeline:
+                                title: Timeline
+                                type: object
+                                description: |-
+                                  The timeline of messages and state changes in the
+                                  room up to the point when the user left.
+                                allOf:
+                                  - $ref: definitions/timeline_batch.yaml
+                              account_data:
+                                title: Account Data
+                                type: object
+                                description: |-
+                                  The private data that this user has attached to
+                                  this room.
+                                allOf:
+                                  - $ref: definitions/event_batch.yaml
+                  presence:
+                    title: Presence
+                    type: object
+                    description: The updates to the presence status of other users.
+                    allOf:
+                      - $ref: definitions/event_batch.yaml
+                  account_data:
+                    title: Account Data
+                    type: object
+                    description: The global private data created by this user.
+                    allOf:
+                      - $ref: definitions/event_batch.yaml
+                  to_device:
+                    title: ToDevice
+                    type: object
+                    description: |-
+                      Information on the send-to-device messages for the client
+                      device, as defined in [Send-to-Device messaging](/client-server-api/#extensions-to-sync).
+                  device_lists:
+                    title: DeviceLists
+                    type: object
+                    description: |-
+                      Information on end-to-end device updates, as specified in
+                      [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
+                  device_one_time_keys_count:
+                    title: One-time keys count
+                    type: object
+                    additionalProperties:
+                      type: integer
+                    description: |-
+                      Information on end-to-end encryption keys, as specified
+                      in [End-to-end encryption](/client-server-api/#e2e-extensions-to-sync).
+                required:
+                  - next_batch
+              examples:
+                response:
+                  value: {
+                    "next_batch": "s72595_4483_1934",
+                    "presence": {
+                      "events": [
+                        {
+                          "$ref": "../../event-schemas/examples/m.presence.yaml"
+                        }
+                      ]
+                    },
+                    "account_data": {
+                      "events": [
+                        {
+                          "type": "org.example.custom.config",
+                          "content": {
+                            "custom_config_key": "custom_config_value"
+                          }
+                        }
+                      ]
+                    },
+                    "rooms": {
+                      "join": {
+                        "!726s6s6q:example.com": {
+                          "summary": {
+                            "m.heroes": [
+                              "@alice:example.com",
+                              "@bob:example.com"
+                            ],
+                            "m.joined_member_count": 2,
+                            "m.invited_member_count": 0
+                          },
+                          "state": {
+                            "events": [
+                              {
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SFHyPlCeYUSFFxlgbQYZmoEoe",
+                                  "displayname": "Example user",
+                                  "membership": "join"
+                                },
+                                "event_id": "$143273976499sgjks:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "state_key": "@example:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 45603,
+                                  "membership": "join"
+                                }
+                              }
+                            ]
+                          },
+                          "timeline": {
+                            "events": [
+                              {
+                                "content": {
+                                  "avatar_url": "mxc://example.org/SEsfnsuifSDFSSEF",
+                                  "displayname": "Alice Margatroid",
+                                  "membership": "join",
+                                  "reason": "Looking for support"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@alice:example.org",
+                                "state_key": "@alice:example.org",
+                                "type": "m.room.member",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
+                              },
+                              {
+                                "content": {
+                                  "body": "This is an example text message",
+                                  "format": "org.matrix.custom.html",
+                                  "formatted_body": "<b>This is an example text message</b>",
+                                  "msgtype": "m.text"
+                                },
+                                "event_id": "$143273582443PhrSn:example.org",
+                                "origin_server_ts": 1432735824653,
+                                "sender": "@example:example.org",
+                                "type": "m.room.message",
+                                "unsigned": {
+                                  "age": 1234,
+                                  "membership": "join"
+                                }
+                              }
+                            ],
+                            "limited": true,
+                            "prev_batch": "t34-23535_0_0"
+                          },
+                          "ephemeral": {
+                            "events": [
+                              {
+                                "$ref": "../../event-schemas/examples/m.typing.yaml"
+                              },
+                              {
+                                "$ref": "../../event-schemas/examples/m.receipt.yaml"
+                              }
+                            ]
+                          },
+                          "account_data": {
+                            "events": [
+                              {
+                                "$ref": "../../event-schemas/examples/m.tag.yaml"
+                              },
+                              {
+                                "type": "org.example.custom.room.config",
+                                "content": {
+                                  "custom_config_key": "custom_config_value"
+                                }
+                              }
+                            ]
+                          },
+                          "unread_notifications": {
+                            "highlight_count": 1,
+                            "notification_count": 5
+                          },
+                          "unread_thread_notifications": {
+                            "$threadroot": {
+                              "highlight_count": 3,
+                              "notification_count": 6
+                            }
+                          }
+                        }
+                      },
+                      "invite": {
+                        "!696r7674:example.com": {
+                          "invite_state": {
+                            "events": [
+                              {
+                                "sender": "@alice:example.com",
+                                "type": "m.room.name",
+                                "state_key": "",
+                                "content": {
+                                  "name": "My Room Name"
+                                }
+                              },
+                              {
+                                "sender": "@alice:example.com",
+                                "type": "m.room.member",
+                                "state_key": "@bob:example.com",
+                                "content": {
+                                  "membership": "invite"
+                                }
+                              }
+                            ]
+                          }
+                        }
+                      },
+                      "knock": {
+                        "!223asd456:example.com": {
+                          "knock_state": {
+                            "events": [
+                              {
+                                "sender": "@alice:example.com",
+                                "type": "m.room.name",
+                                "state_key": "",
+                                "content": {
+                                  "name": "My Room Name"
+                                }
+                              },
+                              {
+                                "sender": "@bob:example.com",
+                                "type": "m.room.member",
+                                "state_key": "@bob:example.com",
+                                "content": {
+                                  "membership": "knock"
+                                }
+                              }
+                            ]
+                          }
+                        }
+                      },
+                      "leave": {}
+                    }
+                  }
+      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