Class MatrixEvent

Typed Event Emitter class which can act as a Base Model for all our model and communication events. This makes it much easier for us to distinguish between events, as we now need to properly type this, so that our events are not stringly-based and prone to silly typos.

Hierarchy

Constructors

Properties

Accessors

Methods

Constructors

  • Construct a Matrix Event object

    Prop

    The raw (possibly encrypted) event. Do not access this property directly unless you absolutely have to. Prefer the getter methods defined on this class. Using the getter methods shields your app from changes to event JSON between Matrix versions.

    Prop

    The room member who sent this event, or null e.g. this is a presence event. This is only guaranteed to be set for events that appear in a timeline, ie. do not guarantee that it will be set on state events.

    Prop

    The room member who is the target of this event, e.g. the invitee, the person being banned, etc.

    Prop

    The sending status of the event.

    Prop

    most recent error associated with sending the event, if any

    Prop

    True if this event is 'forward looking', meaning that getDirectionalContent() will return event.content and not event.prev_content. Default: true. This property is experimental and may change.

    Parameters

    • event: Partial<IEvent> = {}

      The raw event to be wrapped in this DAO

    Returns MatrixEvent

Properties

_cachedExtEv: Optional<ExtensibleEvent<object>> = undefined
_hasCachedExtEv: boolean = false
_isCancelled: boolean = false
_localRedactionEvent: null | MatrixEvent = null
_replacingEvent: null | MatrixEvent = null
claimedEd25519Key: null | string = null
clearEvent?: IClearEvent
decryptionPromise: null | Promise<void> = null
error: null | MatrixError = null
event: Partial<IEvent> = {}

The raw event to be wrapped in this DAO

forwardLooking: boolean = true
forwardingCurve25519KeyChain: string[] = []
localTimestamp: number
pushActions: null | IActionsObject = null
retryDecryption: boolean = false
sender: null | RoomMember = null
senderCurve25519Key: null | string = null
status: null | EventStatus = null
target: null | RoomMember = null
thread?: Thread

A reference to the thread this event belongs to

threadId?: string
txnId?: string
untrusted: null | boolean = null
visibility: MessageVisibility = MESSAGE_VISIBLE

Accessors

  • get threadRootId(): undefined | string
  • Experimental

    Get the event ID of the thread head

    Returns undefined | string

  • get unstableExtensibleEvent(): Optional<ExtensibleEvent<object>>
  • Unstable getter to try and get an extensible event. Note that this might return a falsy value if the event could not be parsed as an extensible event.

    Deprecated

    Use stable functions where possible.

    Returns Optional<ExtensibleEvent<object>>

Methods

  • Change the visibility of an event, as per https://github.com/matrix-org/matrix-doc/pull/3531 .

    Fires

    module:models/event.MatrixEvent#"Event.visibilityChange" if visibilityEvent caused a change in the actual visibility of this event, either by making it visible (if it was hidden), by making it hidden (if it was visible) or by changing the reason (if it was hidden).

    Parameters

    • Optional visibilityChange: IVisibilityChange

      event holding a hide/unhide payload, or nothing if the event is being reset to its original visibility (presumably by a visibility event being redacted).

    Returns void

  • Internal

    Start the process of trying to decrypt this event.

    (This is used within the SDK: it isn't intended for use by applications)

    Returns

    promise which resolves (to undefined) when the decryption attempt is completed.

    Parameters

    Returns Promise<void>

  • Cancel any room key request for this event and resend another.

    Returns

    a promise that resolves when the request is queued

    Parameters

    • crypto: Crypto

      crypto module

    • userId: string

      the user who received this event

    Returns Promise<void>

  • Flags an event as cancelled due to future conditions. For example, a verification request event in the same sync transaction may be flagged as cancelled to warn listeners that a cancellation event is coming down the same pipe shortly.

    Parameters

    • cancelled: boolean = true

      Whether the event is to be cancelled or not.

    Returns void

  • Get the age of this event. This represents the age of the event when the event arrived at the device, and not the age of the event when this function was called. Can only be returned once the server has echo'ed back

    Returns

    The age of this event in milliseconds.

    Returns undefined | number

  • For relations and redactions, returns the event_id this event is referring to.

    Returns

    Returns undefined | string

  • Returns the status of any associated edit or redaction (not for reactions/annotations as their local echo doesn't affect the original event), or else the status of the event.

    Returns

    Returns null | EventStatus

  • Get the ed25519 the sender of this event claims to own.

    For Olm messages, this claim is encoded directly in the plaintext of the event itself. For megolm messages, it is implied by the m.room_key event which established the megolm session.

    Until we download the device list of the sender, it's just a claim: the device list gives a proof that the owner of the curve25519 key used for this event (and returned by #getSenderKey) also owns the ed25519 key by signing the public curve25519 key with the ed25519 key.

    In general, applications should not use this method directly, but should instead use MatrixClient.getEventSenderDeviceInfo.

    Returns

    Returns null | string

  • Gets the cleartext content for this event. If the event is not encrypted, or encryption has not been completed, this will return null.

    Returns

    The cleartext (decrypted) content for the event

    Returns null | IContent

  • Get the (decrypted, if necessary) event content JSON, or the content from the replacing event, if any. See makeReplaced.

    Returns

    The event content JSON, or an empty object.

    Type Parameters

    Returns T

  • Get the timestamp of this event, as a Date object.

    Returns

    The event date, e.g. new Date(1433502692297)

    Returns null | Date

  • Get either 'content' or 'prev_content' depending on if this event is 'forward-looking' or not. This can be modified via event.forwardLooking. In practice, this means we get the chronologically earlier content value for this event (this method should surely be called getEarlierContent) This method is experimental and may change.

    Returns

    event.content if this event is forward-looking, else event.prev_content.

    Returns IContent

  • Gets the event as though it would appear unencrypted. If the event is already not encrypted, it is simply returned as-is.

    Returns

    The event in wire format.

    Returns IEvent

  • Get the curve25519 keys of the devices which were involved in telling us about the claimedEd25519Key and sender curve25519 key.

    Normally this will be empty, but in the case of a forwarded megolm session, the sender keys are sent to us by another device (the forwarding device), which we need to trust to do this. In that case, the result will be a list consisting of one entry.

    If the device that sent us the key (A) got it from another device which it wasn't prepared to vouch for (B), the result will be [A, B]. And so on.

    Returns

    base64-encoded curve25519 keys, from oldest to newest.

    Returns string[]

  • Get the event_id for this event.

    Returns

    The event ID, e.g. $143350589368169JsLZx:localhost

    Returns undefined | string

  • The additional keys the sender of this encrypted event claims to possess.

    Just a wrapper for #getClaimedEd25519Key (q.v.)

    Returns

    Returns Partial<Record<"ed25519", string>>

  • Get the age of the event when this function was called. This is the 'age' field adjusted according to how long this client has had the event.

    Returns

    The age of this event in milliseconds.

    Returns number

  • Get the (decrypted, if necessary) event content JSON, even if the event was replaced by another event.

    Returns

    The event content JSON, or an empty object.

    Type Parameters

    Returns T

  • Get the previous event content JSON. This will only return something for state events which exist in the timeline.

    Returns

    The previous event content JSON, or an empty object.

    Returns IContent

  • Get the (decrypted, if necessary) redaction event JSON if event was redacted

    Returns

    The redaction event JSON, or an empty object

    Returns null | object

  • Get the room_id for this event. This will return undefined for m.presence events.

    Returns

    The room ID, e.g. !cURbafjkfsMDVwdRDQ:matrix.org

    Returns undefined | string

  • Get the user_id for this event.

    Returns

    The user ID, e.g. @alice:matrix.org

    Returns undefined | string

  • The curve25519 key for the device that we think sent this event

    For an Olm-encrypted event, this is inferred directly from the DH exchange at the start of the session: the curve25519 key is involved in the DH exchange, so only a device which holds the private part of that key can establish such a session.

    For a megolm-encrypted event, it is inferred from the Olm message which established the megolm session

    Returns

    Returns null | string

  • Type Parameters

    • T

    Parameters

    • relType: string

    Returns undefined | T

  • Get the event state_key if it has one. This will return undefined for message events.

    Returns

    The event's state_key.

    Returns undefined | string

  • Get the timestamp of this event.

    Returns

    The event timestamp, e.g. 1433502692297

    Returns number

  • Get the (decrypted, if necessary) type of event.

    Returns

    The event type, e.g. m.room.message

    Returns string

  • Get the (possibly encrypted) event content JSON that will be sent to the homeserver.

    Returns

    The event content JSON, or an empty object.

    Returns IContent

  • Get the (possibly encrypted) type of the event that will be sent to the homeserver.

    Returns

    The event type.

    Returns string

  • Replace the event property and recalculate any properties based on it.

    Parameters

    • event: object

      the object to assign to the event property

    Returns void

  • Checks if this event is associated with another event. See getAssociatedId.

    Returns

    Returns boolean

  • Check if this event is currently being decrypted.

    Returns

    True if this event is currently being decrypted, else false.

    Returns boolean

  • Gets whether or not the event is flagged as cancelled. See flagCancelled() for more information.

    Returns

    True if the event is cancelled, false otherwise.

    Returns boolean

  • Check if this event is an encrypted event which we failed to decrypt

    (This implies that we might retry decryption at some point in the future)

    Returns

    True if this event is an encrypted event which we couldn't decrypt.

    Returns boolean

  • Check if the event is encrypted.

    Returns

    True if this event is encrypted.

    Returns boolean

  • Determines if this event is equivalent to the given event. This only checks the event object itself, not the other properties of the event. Intended for use with toSnapshot() to identify events changing.

    Returns

    True if the events are the same, false otherwise.

    Parameters

    • otherEvent: MatrixEvent

      The other event to check against.

    Returns boolean

  • Whether the decryption key was obtained from an untrusted source. If so, we cannot verify the authenticity of the message.

    Returns

    Returns undefined | boolean

  • Check if this event has been redacted

    Returns

    True if this event has been redacted

    Returns boolean

  • Check if this event is a redaction of another event

    Returns

    True if this event is a redaction

    Returns boolean

  • Get whether the event is a relation event, and of a given type if relType is passed in. State events cannot be relation events

    Returns

    Parameters

    • Optional relType: string

      if given, checks that the relation is of the given type

    Returns boolean

  • Whether the event is in any phase of sending, send failure, waiting for remote echo, etc.

    Returns

    Returns boolean

  • Check if this event is a state event.

    Returns

    True if this is a state event.

    Returns boolean

  • Internal

    Replace the content of this event with encrypted versions. (This is used when sending an event; it should not be used by applications).

    Parameters

    • cryptoType: string

      type of the encrypted event - typically "m.room.encrypted"

    • cryptoContent: object

      raw 'content' for the encrypted event.

    • senderCurve25519Key: string

      curve25519 key to record for the sender of this event. See module:models/event.MatrixEvent#getSenderKey.

    • claimedEd25519Key: string

      claimed ed25519 key to record for the sender if this event. See module:models/event.MatrixEvent#getClaimedEd25519Key

    Returns void

  • Update the content of an event in the same way it would be by the server if it were redacted before it was sent to us

    Parameters

    • redactionEvent: MatrixEvent

      event causing the redaction

    Returns void

  • Set an event that replaces the content of this event, through an m.replace relation.

    Fires

    module:models/event.MatrixEvent#"Event.replaced"

    Parameters

    • Optional newEvent: MatrixEvent

      the event with the replacing content, if any.

    Returns void

  • Returns the event replacing the content of this event, if any. Replacements are aggregated on the server, so this would only return an event in case it came down the sync, or for local echo of edits.

    Returns

    Returns null | MatrixEvent

  • Returns the origin_server_ts of the event replacing the content of this event, if any.

    Returns

    Returns undefined | Date

  • Returns the event ID of the event replacing the content of this event, if any.

    Returns

    Returns undefined | string

  • Internal

    Update the cleartext data on this event.

    (This is used after decrypting an event; it should not be used by applications).

    Fires

    module:models/event.MatrixEvent#"Event.decrypted"

    Parameters

    Returns void

  • Parameters

    • Optional threadId: string

    Returns void

  • Summarise the event as JSON. This is currently used by React SDK's view event source feature and Seshat's event indexing, so take care when adjusting the output here.

    If encrypted, include both the decrypted and encrypted view of the event.

    This is named toJSON for use with JSON.stringify which checks objects for functions named toJSON and will call them to customise the output if they are defined.

    Returns

    Returns object

  • Get a copy/snapshot of this event. The returned copy will be loosely linked back to this instance, though will have "frozen" event information. Other properties of this MatrixEvent instance will be copied verbatim, which can mean they are in reference to this instance despite being on the copy too. The reference the snapshot uses does not change, however members aside from the underlying event will not be deeply cloned, thus may be mutated internally. For example, the sender profile will be copied over at snapshot time, and the sender profile internally may mutate without notice to the consumer.

    This is meant to be used to snapshot the event details themselves, not the features (such as sender) surrounding the event.

    Returns

    A snapshot of this event.

    Returns MatrixEvent

  • Update the related id with a new one.

    Used to replace a local id with remote one before sending an event with a related id.

    Parameters

    • eventId: string

      the new event id

    Returns void

Generated using TypeDoc