# 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.

title: ClientEventWithoutRoomID
description: |-
  The format used for events when they are returned from
  API endpoints such as `/sync`, where the `room_id` is implied elsewhere
  in the response.
type: object
required:
  - event_id
  - type
  - sender
  - origin_server_ts
  - content
properties:
  event_id:
    description: The globally unique identifier for this event.
    type: string
    example: '$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45'
  type:
    description: The type of the event.
    type: string
    example: 'm.room.member'
  state_key:
    description: |-
      Present if, and only if, this event is a *state* event. The key making
      this piece of state unique in the room. Note that it is often an empty
      string.

      State keys starting with an `@` are reserved for referencing user IDs, such
      as room members. With the exception of a few events, state events set with a
      given user's ID as the state key MUST only be set by that user.
    type: string
    example: '@user:example.org'
  sender:
    description: Contains the fully-qualified ID of the user who sent this event.
    type: string
    example: "@example:example.org"
  origin_server_ts:
    description: |-
      Timestamp (in milliseconds since the unix epoch) on originating homeserver
      when this event was sent.
    type: integer
    format: int64
    example: 1632489532305
  content:
    description: |-
      The body of this event, as created by the client which sent it.
    type: object
    example: {
      "membership": "join"
    }
  unsigned:
    title: UnsignedData
    type: object
    description: Contains optional extra information about the event.
    properties:
      age:
        description: The time in milliseconds that has elapsed since the event was
          sent. This field is generated by the local homeserver, and may be incorrect
          if the local time on at least one of the two servers is out of sync, which can
          cause the age to either be negative or greater than it actually is.
        type: integer
        format: int64
        example: 1567437
      redacted_because:
        description: The event that redacted this event, if any.
        type: object
        title: ClientEventWithoutRoomID
        example: {
          "type": "m.room.redaction",
          "sender": "@moderator:example.org",
          "content": {
            "reason": "spam"
          },
          "redacts": "$26RqwJMLw-yds1GAH_QxjHRC1Da9oasK0e5VLnck_45",
          "event_id": "$Nhl3rsgHMjk-DjMJANawr9HHAhLg4GcoTYrSiYYGqEE",
          "origin_server_ts": 1632491098485,
          "unsigned": {
            "age": 1257,
            "membership": "leave"
          }
        }
      transaction_id:
        description: |
          The client-supplied [transaction ID](/client-server-api/#transaction-identifiers), for example, provided via
          `PUT /_matrix/client/v3/rooms/{roomId}/send/{eventType}/{txnId}`,
          if the client being given the event is the same one which sent it.
        type: string
      prev_content:
        description: |
          The previous `content` for this event. This field is generated
          by the local homeserver, and is only returned if the event is a state event,
          and the client has permission to see the previous content.
        x-changedInMatrixVersion:
          "1.2": |
            Previously, this field was specified at the top level of returned
            events rather than in `unsigned` (with the exception of the [`GET
            .../notifications`](/client-server-api/#get_matrixclientv3notifications)
            endpoint), though in practice no known server implementations honoured
            this.
        title: EventContent
        type: object
      membership:
        description: |
          The room membership of the user making the request, at the time of the event.

          This property is the value of the `membership` property of the
          requesting user's [`m.room.member`](/client-server-api#mroommember)
          state at the point of the event, including any changes caused by the
          event. If the user had yet to join the room at the time of the event
          (i.e, they have no `m.room.member` state), this property is set to
          `leave`.

          Homeservers SHOULD populate this property
          wherever practical, but they MAY omit it if necessary (for example,
          if calculating the value is expensive, servers might choose to only
          implement it in encrypted rooms). The property is *not* normally populated
          in events pushed to application services via the application service transaction API
          (where there is no clear definition of "requesting user").
        type: string
        example: join
        x-addedInMatrixVersion: "1.11"
