mautrix

package module
v0.22.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 16, 2024 License: MPL-2.0 Imports: 34 Imported by: 177

README

mautrix-go

GoDoc

A Golang Matrix framework. Used by gomuks, go-neb, mautrix-whatsapp and others.

Matrix room: #go:maunium.net

This project is based on matrix-org/gomatrix. The original project is licensed under Apache 2.0.

In addition to the basic client API features the original project has, this framework also has:

  • Appservice support (Intent API like mautrix-python, room state storage, etc)
  • End-to-end encryption support (incl. interactive SAS verification)
  • High-level module for building puppeting bridges
  • High-level module for building chat clients
  • Wrapper functions for the Synapse admin API
  • Structs for parsing event content
  • Helpers for parsing and generating Matrix HTML
  • Helpers for handling push rules

Documentation

Overview

Package mautrix implements the Matrix Client-Server API.

Specification can be found at https://spec.matrix.org/v1.2/client-server-api/

Index

Constants

View Source
const (
	LogBodyContextKey contextKey = iota
	LogRequestIDContextKey
)
View Source
const (
	IdentifierTypeUser       = "m.id.user"
	IdentifierTypeThirdParty = "m.id.thirdparty"
	IdentifierTypePhone      = "m.id.phone"
)
View Source
const Version = "v0.22.0"

Variables

View Source
var (
	// Generic error for when the server encounters an error and it does not have a more specific error code.
	// Note that `errors.Is` will check the error message rather than code for M_UNKNOWNs.
	MUnknown = RespError{ErrCode: "M_UNKNOWN", StatusCode: http.StatusInternalServerError}
	// Forbidden access, e.g. joining a room without permission, failed login.
	MForbidden = RespError{ErrCode: "M_FORBIDDEN", StatusCode: http.StatusForbidden}
	// Unrecognized request, e.g. the endpoint does not exist or is not implemented.
	MUnrecognized = RespError{ErrCode: "M_UNRECOGNIZED", StatusCode: http.StatusNotFound}
	// The access token specified was not recognised.
	MUnknownToken = RespError{ErrCode: "M_UNKNOWN_TOKEN", StatusCode: http.StatusUnauthorized}
	// No access token was specified for the request.
	MMissingToken = RespError{ErrCode: "M_MISSING_TOKEN", StatusCode: http.StatusUnauthorized}
	// Request contained valid JSON, but it was malformed in some way, e.g. missing required keys, invalid values for keys.
	MBadJSON = RespError{ErrCode: "M_BAD_JSON", StatusCode: http.StatusBadRequest}
	// Request did not contain valid JSON.
	MNotJSON = RespError{ErrCode: "M_NOT_JSON", StatusCode: http.StatusBadRequest}
	// No resource was found for this request.
	MNotFound = RespError{ErrCode: "M_NOT_FOUND", StatusCode: http.StatusNotFound}
	// Too many requests have been sent in a short period of time. Wait a while then try again.
	MLimitExceeded = RespError{ErrCode: "M_LIMIT_EXCEEDED", StatusCode: http.StatusTooManyRequests}
	// The user ID associated with the request has been deactivated.
	// Typically for endpoints that prove authentication, such as /login.
	MUserDeactivated = RespError{ErrCode: "M_USER_DEACTIVATED"}
	// Encountered when trying to register a user ID which has been taken.
	MUserInUse = RespError{ErrCode: "M_USER_IN_USE", StatusCode: http.StatusBadRequest}
	// Encountered when trying to register a user ID which is not valid.
	MInvalidUsername = RespError{ErrCode: "M_INVALID_USERNAME", StatusCode: http.StatusBadRequest}
	// Sent when the room alias given to the createRoom API is already in use.
	MRoomInUse = RespError{ErrCode: "M_ROOM_IN_USE", StatusCode: http.StatusBadRequest}
	// The state change requested cannot be performed, such as attempting to unban a user who is not banned.
	MBadState = RespError{ErrCode: "M_BAD_STATE"}
	// The request or entity was too large.
	MTooLarge = RespError{ErrCode: "M_TOO_LARGE", StatusCode: http.StatusRequestEntityTooLarge}
	// The resource being requested is reserved by an application service, or the application service making the request has not created the resource.
	MExclusive = RespError{ErrCode: "M_EXCLUSIVE", StatusCode: http.StatusBadRequest}
	// The client's request to create a room used a room version that the server does not support.
	MUnsupportedRoomVersion = RespError{ErrCode: "M_UNSUPPORTED_ROOM_VERSION"}
	// The client attempted to join a room that has a version the server does not support.
	// Inspect the room_version property of the error response for the room's version.
	MIncompatibleRoomVersion = RespError{ErrCode: "M_INCOMPATIBLE_ROOM_VERSION"}
	// The client specified a parameter that has the wrong value.
	MInvalidParam = RespError{ErrCode: "M_INVALID_PARAM", StatusCode: http.StatusBadRequest}

	MURLNotSet         = RespError{ErrCode: "M_URL_NOT_SET"}
	MBadStatus         = RespError{ErrCode: "M_BAD_STATUS"}
	MConnectionTimeout = RespError{ErrCode: "M_CONNECTION_TIMEOUT"}
	MConnectionFailed  = RespError{ErrCode: "M_CONNECTION_FAILED"}
)

Common error codes from https://matrix.org/docs/spec/client_server/latest#api-standards

Can be used with errors.Is() to check the response code without casting the error:

err := client.Sync()
if errors.Is(err, MUnknownToken) {
	// logout
}
View Source
var (
	FeatureAsyncUploads       = UnstableFeature{UnstableFlag: "fi.mau.msc2246.stable", SpecVersion: SpecV17}
	FeatureAppservicePing     = UnstableFeature{UnstableFlag: "fi.mau.msc2659.stable", SpecVersion: SpecV17}
	FeatureAuthenticatedMedia = UnstableFeature{UnstableFlag: "org.matrix.msc3916.stable", SpecVersion: SpecV111}

	BeeperFeatureHungry               = UnstableFeature{UnstableFlag: "com.beeper.hungry"}
	BeeperFeatureBatchSending         = UnstableFeature{UnstableFlag: "com.beeper.batch_sending"}
	BeeperFeatureRoomYeeting          = UnstableFeature{UnstableFlag: "com.beeper.room_yeeting"}
	BeeperFeatureAutojoinInvites      = UnstableFeature{UnstableFlag: "com.beeper.room_create_autojoin_invites"}
	BeeperFeatureArbitraryProfileMeta = UnstableFeature{UnstableFlag: "com.beeper.arbitrary_profile_meta"}
	BeeperFeatureAccountDataMute      = UnstableFeature{UnstableFlag: "com.beeper.account_data_mute"}
	BeeperFeatureInboxState           = UnstableFeature{UnstableFlag: "com.beeper.inbox_state"}
)
View Source
var (
	SpecR000 = MustParseSpecVersion("r0.0.0")
	SpecR001 = MustParseSpecVersion("r0.0.1")
	SpecR010 = MustParseSpecVersion("r0.1.0")
	SpecR020 = MustParseSpecVersion("r0.2.0")
	SpecR030 = MustParseSpecVersion("r0.3.0")
	SpecR040 = MustParseSpecVersion("r0.4.0")
	SpecR050 = MustParseSpecVersion("r0.5.0")
	SpecR060 = MustParseSpecVersion("r0.6.0")
	SpecR061 = MustParseSpecVersion("r0.6.1")
	SpecV11  = MustParseSpecVersion("v1.1")
	SpecV12  = MustParseSpecVersion("v1.2")
	SpecV13  = MustParseSpecVersion("v1.3")
	SpecV14  = MustParseSpecVersion("v1.4")
	SpecV15  = MustParseSpecVersion("v1.5")
	SpecV16  = MustParseSpecVersion("v1.6")
	SpecV17  = MustParseSpecVersion("v1.7")
	SpecV18  = MustParseSpecVersion("v1.8")
	SpecV19  = MustParseSpecVersion("v1.9")
	SpecV110 = MustParseSpecVersion("v1.10")
	SpecV111 = MustParseSpecVersion("v1.11")
)
View Source
var Commit = ""
View Source
var DefaultUserAgent = "mautrix-go/" + Version + " go/" + strings.TrimPrefix(runtime.Version(), "go")
View Source
var GoModVersion = ""
View Source
var VersionWithCommit = Version

Functions

func BuildURL added in v0.9.18

func BuildURL(baseURL *url.URL, path ...any) *url.URL

BuildURL builds a URL with the given path parts

func ParseAndNormalizeBaseURL added in v0.15.0

func ParseAndNormalizeBaseURL(homeserverURL string) (*url.URL, error)

func ParseErrorResponse added in v0.15.3

func ParseErrorResponse(req *http.Request, res *http.Response) ([]byte, error)

func UpdateStateStore added in v0.15.0

func UpdateStateStore(ctx context.Context, store StateStore, evt *event.Event)

Types

type AccountDataStore added in v0.8.1

type AccountDataStore struct {
	FilterID  string
	EventType string
	// contains filtered or unexported fields
}

AccountDataStore uses account data to store the next batch token, and stores the filter ID in memory (as filters can be safely recreated every startup).

func NewAccountDataStore added in v0.8.1

func NewAccountDataStore(eventType string, client *Client) *AccountDataStore

NewAccountDataStore returns a new AccountDataStore, which stores the next_batch token as a custom event in account data in the homeserver.

AccountDataStore is only appropriate for bots, not appservices.

The event type should be a reversed DNS name like tld.domain.sub.internal and must be unique for a client. The data stored in it is considered internal and must not be modified through outside means. You should also add a filter for account data changes of this event type, to avoid ending up in a sync loop:

filter := mautrix.Filter{
	AccountData: mautrix.FilterPart{
		Limit: 20,
		NotTypes: []event.Type{
			event.NewEventType(eventType),
		},
	},
}
// If you use a custom Syncer, set the filter there, not like this
client.Syncer.(*mautrix.DefaultSyncer).FilterJSON = &filter
client.Store = mautrix.NewAccountDataStore("com.example.mybot.store", client)
go func() {
	err := client.Sync()
	// don't forget to check err
}()

func (*AccountDataStore) LoadFilterID added in v0.15.0

func (s *AccountDataStore) LoadFilterID(ctx context.Context, userID id.UserID) (string, error)

func (*AccountDataStore) LoadNextBatch added in v0.8.1

func (s *AccountDataStore) LoadNextBatch(ctx context.Context, userID id.UserID) (string, error)

func (*AccountDataStore) SaveFilterID added in v0.15.0

func (s *AccountDataStore) SaveFilterID(ctx context.Context, userID id.UserID, filterID string) error

func (*AccountDataStore) SaveNextBatch added in v0.8.1

func (s *AccountDataStore) SaveNextBatch(ctx context.Context, userID id.UserID, nextBatchToken string) error

type AuthType added in v0.7.1

type AuthType string
const (
	AuthTypePassword   AuthType = "m.login.password"
	AuthTypeReCAPTCHA  AuthType = "m.login.recaptcha"
	AuthTypeOAuth2     AuthType = "m.login.oauth2"
	AuthTypeSSO        AuthType = "m.login.sso"
	AuthTypeEmail      AuthType = "m.login.email.identity"
	AuthTypeMSISDN     AuthType = "m.login.msisdn"
	AuthTypeToken      AuthType = "m.login.token"
	AuthTypeDummy      AuthType = "m.login.dummy"
	AuthTypeAppservice AuthType = "m.login.application_service"

	AuthTypeSynapseJWT AuthType = "org.matrix.login.jwt"

	AuthTypeDevtureSharedSecret AuthType = "com.devture.shared_secret_auth"
)

type BaseAuthData added in v0.7.1

type BaseAuthData struct {
	Type    AuthType `json:"type"`
	Session string   `json:"session,omitempty"`
}

type BaseURLPath added in v0.11.0

type BaseURLPath []any

func (BaseURLPath) FullPath added in v0.11.0

func (bup BaseURLPath) FullPath() []any

type BeeperInboxDone added in v0.20.0

type BeeperInboxDone struct {
	Delta   int64 `json:"at_delta"`
	AtOrder int64 `json:"at_order"`
}

type BeeperInboxPreviewEvent added in v0.18.0

type BeeperInboxPreviewEvent struct {
	EventID   id.EventID         `json:"event_id"`
	Timestamp jsontime.UnixMilli `json:"origin_server_ts"`
	Event     *event.Event       `json:"event,omitempty"`
}

type BeeperSplitRoomPart added in v0.12.4

type BeeperSplitRoomPart struct {
	UserID  id.UserID     `json:"user_id"`
	Values  []string      `json:"values"`
	NewRoom ReqCreateRoom `json:"create"`
}

type CapBoolean added in v0.12.0

type CapBoolean struct {
	Enabled bool `json:"enabled"`
}

type CapBooleanFalse added in v0.12.0

type CapBooleanFalse CapBoolean

func (*CapBooleanFalse) IsEnabled added in v0.12.0

func (cb *CapBooleanFalse) IsEnabled() bool

IsEnabled returns true if the capability is enabled explicitly. If it's not specified, this returns false.

type CapBooleanTrue added in v0.12.0

type CapBooleanTrue CapBoolean

func (*CapBooleanTrue) IsEnabled added in v0.12.0

func (cb *CapBooleanTrue) IsEnabled() bool

IsEnabled returns true if the capability is either enabled explicitly or not specified (nil)

type CapRoomVersionStability added in v0.12.0

type CapRoomVersionStability string
const (
	CapRoomVersionStable   CapRoomVersionStability = "stable"
	CapRoomVersionUnstable CapRoomVersionStability = "unstable"
)

type CapRoomVersions added in v0.12.0

type CapRoomVersions struct {
	Default   string                             `json:"default"`
	Available map[string]CapRoomVersionStability `json:"available"`
}

func (*CapRoomVersions) IsAvailable added in v0.12.0

func (vers *CapRoomVersions) IsAvailable(version string) bool

func (*CapRoomVersions) IsStable added in v0.12.0

func (vers *CapRoomVersions) IsStable(version string) bool

type ChildRoomsChunk added in v0.12.3

type ChildRoomsChunk struct {
	AvatarURL        id.ContentURI           `json:"avatar_url,omitempty"`
	CanonicalAlias   id.RoomAlias            `json:"canonical_alias,omitempty"`
	ChildrenState    []StrippedStateWithTime `json:"children_state"`
	GuestCanJoin     bool                    `json:"guest_can_join"`
	JoinRule         event.JoinRule          `json:"join_rule,omitempty"`
	Name             string                  `json:"name,omitempty"`
	NumJoinedMembers int                     `json:"num_joined_members"`
	RoomID           id.RoomID               `json:"room_id"`
	RoomType         event.RoomType          `json:"room_type"`
	Topic            string                  `json:"topic,omitempty"`
	WorldReadble     bool                    `json:"world_readable"`
}

type Client

type Client struct {
	HomeserverURL *url.URL     // The base homeserver URL
	UserID        id.UserID    // The user ID of the client. Used for forming HTTP paths which use the client's user ID.
	DeviceID      id.DeviceID  // The device ID of the client.
	AccessToken   string       // The access_token for the client.
	UserAgent     string       // The value for the User-Agent header
	Client        *http.Client // The underlying HTTP client which will be used to make HTTP requests.
	Syncer        Syncer       // The thing which can process /sync responses
	Store         SyncStore    // The thing which can store tokens/ids
	StateStore    StateStore
	Crypto        CryptoHelper
	Verification  VerificationHelper
	SpecVersions  *RespVersions

	Log zerolog.Logger

	RequestHook  func(req *http.Request)
	ResponseHook func(req *http.Request, resp *http.Response, err error, duration time.Duration)

	UpdateRequestOnRetry func(req *http.Request, cause error) *http.Request

	SyncPresence event.Presence
	SyncTraceLog bool

	StreamSyncMinAge time.Duration

	// Number of times that mautrix will retry any HTTP request
	// if the request fails entirely or returns a HTTP gateway error (502-504)
	DefaultHTTPRetries int
	// Amount of time to wait between HTTP retries, defaults to 4 seconds
	DefaultHTTPBackoff time.Duration
	// Set to true to disable automatically sleeping on 429 errors.
	IgnoreRateLimit bool

	// Should the ?user_id= query parameter be set in requests?
	// See https://spec.matrix.org/v1.6/application-service-api/#identity-assertion
	SetAppServiceUserID bool
	// Should the org.matrix.msc3202.device_id query parameter be set in requests?
	// See https://github.com/matrix-org/matrix-spec-proposals/pull/3202
	SetAppServiceDeviceID bool
	// contains filtered or unexported fields
}

Client represents a Matrix client.

func NewClient

func NewClient(homeserverURL string, userID id.UserID, accessToken string) (*Client, error)

NewClient creates a new Matrix Client ready for syncing

func (*Client) AddTag

func (cli *Client) AddTag(ctx context.Context, roomID id.RoomID, tag event.RoomTag, order float64) error

func (*Client) AddTagWithCustomData added in v0.9.8

func (cli *Client) AddTagWithCustomData(ctx context.Context, roomID id.RoomID, tag event.RoomTag, data any) (err error)

func (*Client) AppservicePing added in v0.15.0

func (cli *Client) AppservicePing(ctx context.Context, id, txnID string) (resp *RespAppservicePing, err error)

func (*Client) BanUser

func (cli *Client) BanUser(ctx context.Context, roomID id.RoomID, req *ReqBanUser) (resp *RespBanUser, err error)

BanUser bans a user from a room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidban

func (*Client) BatchSend deprecated added in v0.9.30

func (cli *Client) BatchSend(ctx context.Context, roomID id.RoomID, req *ReqBatchSend) (resp *RespBatchSend, err error)

BatchSend sends a batch of historical events into a room. This is only available for appservices.

Deprecated: MSC2716 has been abandoned, so this is now Beeper-specific. BeeperBatchSend should be used instead.

func (*Client) BeeperBatchSend added in v0.15.4

func (cli *Client) BeeperBatchSend(ctx context.Context, roomID id.RoomID, req *ReqBeeperBatchSend) (resp *RespBeeperBatchSend, err error)

func (*Client) BeeperDeleteRoom added in v0.13.0

func (cli *Client) BeeperDeleteRoom(ctx context.Context, roomID id.RoomID) (err error)

func (*Client) BeeperMergeRooms added in v0.12.4

func (cli *Client) BeeperMergeRooms(ctx context.Context, req *ReqBeeperMergeRoom) (resp *RespBeeperMergeRoom, err error)

func (*Client) BeeperSplitRoom added in v0.12.4

func (cli *Client) BeeperSplitRoom(ctx context.Context, req *ReqBeeperSplitRoom) (resp *RespBeeperSplitRoom, err error)

func (*Client) BeeperUpdateProfile added in v0.15.1

func (cli *Client) BeeperUpdateProfile(ctx context.Context, data any) (err error)

BeeperUpdateProfile sets custom fields in the user's profile.

func (*Client) BuildClientURL added in v0.11.0

func (cli *Client) BuildClientURL(urlPath ...any) string

BuildClientURL builds a URL with the Client's homeserver and appservice user ID set already. This method also automatically prepends the client API prefix (/_matrix/client).

func (*Client) BuildURL

func (cli *Client) BuildURL(urlPath PrefixableURLPath) string

BuildURL builds a URL with the Client's homeserver and appservice user ID set already.

func (*Client) BuildURLWithQuery

func (cli *Client) BuildURLWithQuery(urlPath PrefixableURLPath, urlQuery map[string]string) string

BuildURLWithQuery builds a URL with query parameters in addition to the Client's homeserver and appservice user ID set already.

func (*Client) Capabilities added in v0.12.0

func (cli *Client) Capabilities(ctx context.Context) (resp *RespCapabilities, err error)

Capabilities returns capabilities on this homeserver. See https://spec.matrix.org/v1.3/client-server-api/#capabilities-negotiation

func (*Client) ClaimKeys

func (cli *Client) ClaimKeys(ctx context.Context, req *ReqClaimKeys) (resp *RespClaimKeys, err error)

func (*Client) ClearCredentials

func (cli *Client) ClearCredentials()

ClearCredentials removes the user ID and access token on this client instance.

func (*Client) Context added in v0.10.9

func (cli *Client) Context(ctx context.Context, roomID id.RoomID, eventID id.EventID, filter *FilterPart, limit int) (resp *RespContext, err error)

Context returns a number of events that happened just before and after the specified event. It use pagination query parameters to paginate history in the room. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidcontexteventid

func (*Client) CreateAlias

func (cli *Client) CreateAlias(ctx context.Context, alias id.RoomAlias, roomID id.RoomID) (resp *RespAliasCreate, err error)

func (*Client) CreateFilter

func (cli *Client) CreateFilter(ctx context.Context, filter *Filter) (resp *RespCreateFilter, err error)

CreateFilter makes an HTTP request according to https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3useruseridfilter

func (*Client) CreateKeyBackupVersion added in v0.18.0

func (cli *Client) CreateKeyBackupVersion(ctx context.Context, req *ReqRoomKeysVersionCreate[backup.MegolmAuthData]) (resp *RespRoomKeysVersionCreate, err error)

CreateKeyBackupVersion creates a new key backup.

See: https://spec.matrix.org/v1.9/client-server-api/#post_matrixclientv3room_keysversion

func (*Client) CreateMXC added in v0.15.3

func (cli *Client) CreateMXC(ctx context.Context, extra ...ReqCreateMXC) (*RespCreateMXC, error)

CreateMXC creates a blank Matrix content URI to allow uploading the content asynchronously later.

See https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create

func (*Client) CreateRoom

func (cli *Client) CreateRoom(ctx context.Context, req *ReqCreateRoom) (resp *RespCreateRoom, err error)

CreateRoom creates a new Matrix room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom

resp, err := cli.CreateRoom(&mautrix.ReqCreateRoom{
	Preset: "public_chat",
})
fmt.Println("Room:", resp.RoomID)

func (*Client) DeleteAlias

func (cli *Client) DeleteAlias(ctx context.Context, alias id.RoomAlias) (resp *RespAliasDelete, err error)

func (*Client) DeleteDevice added in v0.8.3

func (cli *Client) DeleteDevice(ctx context.Context, deviceID id.DeviceID, req *ReqDeleteDevice) error

func (*Client) DeleteDevices added in v0.8.3

func (cli *Client) DeleteDevices(ctx context.Context, req *ReqDeleteDevices) error

func (*Client) DeleteKeyBackup added in v0.18.0

func (cli *Client) DeleteKeyBackup(ctx context.Context, version id.KeyBackupVersion) (resp *RespRoomKeysUpdate, err error)

DeleteKeyBackup deletes all keys from the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#delete_matrixclientv3room_keyskeys

func (*Client) DeleteKeyBackupVersion added in v0.18.0

func (cli *Client) DeleteKeyBackupVersion(ctx context.Context, version id.KeyBackupVersion) error

DeleteKeyBackupVersion deletes an existing key backup. Both the information about the backup, as well as all key data related to the backup will be deleted.

See: https://spec.matrix.org/v1.1/client-server-api/#delete_matrixclientv3room_keysversionversion

func (*Client) DeleteKeysFromBackupForRoom added in v0.18.0

func (cli *Client) DeleteKeysFromBackupForRoom(ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID) (resp *RespRoomKeysUpdate, err error)

DeleteKeysFromBackupForRoom deletes all the keys in the backup for the given room.

See: https://spec.matrix.org/v1.9/client-server-api/#delete_matrixclientv3room_keyskeysroomid

func (*Client) DeleteKeysInBackupForRoomAndSession added in v0.18.0

func (cli *Client) DeleteKeysInBackupForRoomAndSession(ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID, sessionID id.SessionID) (resp *RespRoomKeysUpdate, err error)

DeleteKeysInBackupForRoomAndSession deletes a key from the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#delete_matrixclientv3room_keyskeysroomidsessionid

func (*Client) DeletePushRule added in v0.4.11

func (cli *Client) DeletePushRule(ctx context.Context, scope string, kind pushrules.PushRuleType, ruleID string) error

func (*Client) DontProcessOldEvents added in v0.15.3

func (cli *Client) DontProcessOldEvents(_ context.Context, resp *RespSync, since string) bool

DontProcessOldEvents is a sync handler that removes rooms that the user just joined. It's meant for bots to ignore events from before the bot joined the room.

To use it, register it with your Syncer, e.g.:

cli.Syncer.(mautrix.ExtensibleSyncer).OnSync(cli.DontProcessOldEvents)

func (*Client) Download

func (cli *Client) Download(ctx context.Context, mxcURL id.ContentURI) (*http.Response, error)

func (*Client) DownloadBytes

func (cli *Client) DownloadBytes(ctx context.Context, mxcURL id.ContentURI) ([]byte, error)

func (*Client) ForgetRoom

func (cli *Client) ForgetRoom(ctx context.Context, roomID id.RoomID) (resp *RespForgetRoom, err error)

ForgetRoom forgets a room entirely. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidforget

func (*Client) FullSyncRequest added in v0.9.25

func (cli *Client) FullSyncRequest(ctx context.Context, req ReqSync) (resp *RespSync, err error)

FullSyncRequest makes an HTTP request according to https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3sync

func (*Client) GetAccountData added in v0.7.2

func (cli *Client) GetAccountData(ctx context.Context, name string, output interface{}) (err error)

GetAccountData gets the user's account data of this type. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3useruseridaccount_datatype

func (*Client) GetAliases added in v0.11.0

func (cli *Client) GetAliases(ctx context.Context, roomID id.RoomID) (resp *RespAliasList, err error)

func (*Client) GetAvatarURL

func (cli *Client) GetAvatarURL(ctx context.Context, mxid id.UserID) (url id.ContentURI, err error)

GetAvatarURL gets the avatar URL of the user with the specified MXID. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3profileuseridavatar_url

func (*Client) GetDeviceInfo added in v0.8.3

func (cli *Client) GetDeviceInfo(ctx context.Context, deviceID id.DeviceID) (resp *RespDeviceInfo, err error)

func (*Client) GetDevicesInfo added in v0.8.3

func (cli *Client) GetDevicesInfo(ctx context.Context) (resp *RespDevicesInfo, err error)

func (*Client) GetDisplayName

func (cli *Client) GetDisplayName(ctx context.Context, mxid id.UserID) (resp *RespUserDisplayName, err error)

GetDisplayName returns the display name of the user with the specified MXID. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3profileuseriddisplayname

func (*Client) GetEvent

func (cli *Client) GetEvent(ctx context.Context, roomID id.RoomID, eventID id.EventID) (resp *event.Event, err error)

func (*Client) GetKeyBackup added in v0.18.0

GetKeyBackup retrieves the keys from the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3room_keyskeys

func (*Client) GetKeyBackupForRoom added in v0.18.0

func (cli *Client) GetKeyBackupForRoom(
	ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID,
) (resp *RespRoomKeyBackup[backup.EncryptedSessionData[backup.MegolmSessionData]], err error)

GetKeyBackupForRoom retrieves the keys from the backup for the given room.

See: https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3room_keyskeysroomid

func (*Client) GetKeyBackupForRoomAndSession added in v0.18.0

func (cli *Client) GetKeyBackupForRoomAndSession(
	ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID, sessionID id.SessionID,
) (resp *RespKeyBackupData[backup.EncryptedSessionData[backup.MegolmSessionData]], err error)

GetKeyBackupForRoomAndSession retrieves a key from the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3room_keyskeysroomidsessionid

func (*Client) GetKeyBackupLatestVersion added in v0.18.0

func (cli *Client) GetKeyBackupLatestVersion(ctx context.Context) (resp *RespRoomKeysVersion[backup.MegolmAuthData], err error)

GetKeyBackupLatestVersion returns information about the latest backup version.

See: https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3room_keysversion

func (*Client) GetKeyBackupVersion added in v0.18.0

func (cli *Client) GetKeyBackupVersion(ctx context.Context, version id.KeyBackupVersion) (resp *RespRoomKeysVersion[backup.MegolmAuthData], err error)

GetKeyBackupVersion returns information about an existing key backup.

See: https://spec.matrix.org/v1.9/client-server-api/#get_matrixclientv3room_keysversionversion

func (*Client) GetKeyChanges

func (cli *Client) GetKeyChanges(ctx context.Context, from, to string) (resp *RespKeyChanges, err error)

func (*Client) GetLoginFlows

func (cli *Client) GetLoginFlows(ctx context.Context) (resp *RespLoginFlows, err error)

GetLoginFlows fetches the login flows that the homeserver supports using https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3login

func (*Client) GetMediaConfig added in v0.12.2

func (cli *Client) GetMediaConfig(ctx context.Context) (resp *RespMediaConfig, err error)

GetMediaConfig fetches the configuration of the content repository, such as upload limitations.

func (*Client) GetOwnAvatarURL added in v0.7.5

func (cli *Client) GetOwnAvatarURL(ctx context.Context) (url id.ContentURI, err error)

GetOwnAvatarURL gets the user's avatar URL. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3profileuseridavatar_url

func (*Client) GetOwnDisplayName

func (cli *Client) GetOwnDisplayName(ctx context.Context) (resp *RespUserDisplayName, err error)

GetOwnDisplayName returns the user's display name. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3profileuseriddisplayname

func (*Client) GetOwnPresence added in v0.9.2

func (cli *Client) GetOwnPresence(ctx context.Context) (resp *RespPresence, err error)

GetOwnPresence gets the user's presence. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3presenceuseridstatus

func (*Client) GetPresence added in v0.9.2

func (cli *Client) GetPresence(ctx context.Context, userID id.UserID) (resp *RespPresence, err error)

GetPresence gets the presence of the user with the specified MXID. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3presenceuseridstatus

func (*Client) GetProfile added in v0.12.4

func (cli *Client) GetProfile(ctx context.Context, mxid id.UserID) (resp *RespUserProfile, err error)

func (*Client) GetPushRule added in v0.4.11

func (cli *Client) GetPushRule(ctx context.Context, scope string, kind pushrules.PushRuleType, ruleID string) (resp *pushrules.PushRule, err error)

func (*Client) GetPushRules

func (cli *Client) GetPushRules(ctx context.Context) (*pushrules.PushRuleset, error)

GetPushRules returns the push notification rules for the global scope.

func (*Client) GetRoomAccountData added in v0.9.8

func (cli *Client) GetRoomAccountData(ctx context.Context, roomID id.RoomID, name string, output interface{}) (err error)

GetRoomAccountData gets the user's account data of this type in a specific room. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3useruseridaccount_datatype

func (*Client) GetScopedPushRules

func (cli *Client) GetScopedPushRules(ctx context.Context, scope string) (resp *pushrules.PushRuleset, err error)

GetScopedPushRules returns the push notification rules for the given scope.

func (*Client) GetTags added in v0.9.8

func (cli *Client) GetTags(ctx context.Context, roomID id.RoomID) (tags event.TagEventContent, err error)

func (*Client) GetTagsWithCustomData added in v0.9.8

func (cli *Client) GetTagsWithCustomData(ctx context.Context, roomID id.RoomID, resp any) (err error)

func (*Client) GetURLPreview added in v0.10.11

func (cli *Client) GetURLPreview(ctx context.Context, url string) (*RespPreviewURL, error)

GetURLPreview asks the homeserver to fetch a preview for a given URL.

See https://spec.matrix.org/v1.2/client-server-api/#get_matrixmediav3preview_url

func (*Client) Hierarchy added in v0.12.3

func (cli *Client) Hierarchy(ctx context.Context, roomID id.RoomID, req *ReqHierarchy) (resp *RespHierarchy, err error)

Hierarchy returns a list of rooms that are in the room's hierarchy. See https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv1roomsroomidhierarchy

The hierarchy API is provided to walk the space tree and discover the rooms with their aesthetic details. works in a depth-first manner: when it encounters another space as a child it recurses into that space before returning non-space children.

The second function parameter specifies query parameters to limit the response. No query parameters will be added if it's nil.

func (*Client) InviteUser

func (cli *Client) InviteUser(ctx context.Context, roomID id.RoomID, req *ReqInviteUser) (resp *RespInviteUser, err error)

InviteUser invites a user to a room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite

func (*Client) InviteUserByThirdParty

func (cli *Client) InviteUserByThirdParty(ctx context.Context, roomID id.RoomID, req *ReqInvite3PID) (resp *RespInviteUser, err error)

InviteUserByThirdParty invites a third-party identifier to a room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite-1

func (*Client) JoinRoom

func (cli *Client) JoinRoom(ctx context.Context, roomIDorAlias, serverName string, content interface{}) (resp *RespJoinRoom, err error)

JoinRoom joins the client to a room ID or alias. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3joinroomidoralias

If serverName is specified, this will be added as a query param to instruct the homeserver to join via that server. If content is specified, it will be JSON encoded and used as the request body.

func (*Client) JoinRoomByID added in v0.3.5

func (cli *Client) JoinRoomByID(ctx context.Context, roomID id.RoomID) (resp *RespJoinRoom, err error)

JoinRoomByID joins the client to a room ID. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidjoin

Unlike JoinRoom, this method can only be used to join rooms that the server already knows about. It's mostly intended for bridges and other things where it's already certain that the server is in the room.

func (*Client) JoinedMembers

func (cli *Client) JoinedMembers(ctx context.Context, roomID id.RoomID) (resp *RespJoinedMembers, err error)

JoinedMembers returns a map of joined room members. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidjoined_members

In general, usage of this API is discouraged in favour of /sync, as calling this API can race with incoming membership changes. This API is primarily designed for application services which may want to efficiently look up joined members in a room.

func (*Client) JoinedRooms

func (cli *Client) JoinedRooms(ctx context.Context) (resp *RespJoinedRooms, err error)

JoinedRooms returns a list of rooms which the client is joined to. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3joined_rooms

In general, usage of this API is discouraged in favour of /sync, as calling this API can race with incoming membership changes. This API is primarily designed for application services which may want to efficiently look up joined rooms.

func (*Client) KickUser

func (cli *Client) KickUser(ctx context.Context, roomID id.RoomID, req *ReqKickUser) (resp *RespKickUser, err error)

KickUser kicks a user from a room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidkick

func (*Client) LeaveRoom

func (cli *Client) LeaveRoom(ctx context.Context, roomID id.RoomID, optionalReq ...*ReqLeave) (resp *RespLeaveRoom, err error)

LeaveRoom leaves the given room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidleave

func (*Client) LogRequestDone added in v0.12.0

func (cli *Client) LogRequestDone(req *http.Request, resp *http.Response, err error, handlerErr error, contentLength int, duration time.Duration)

func (*Client) Login

func (cli *Client) Login(ctx context.Context, req *ReqLogin) (resp *RespLogin, err error)

Login a user to the homeserver according to https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3login

func (*Client) Logout

func (cli *Client) Logout(ctx context.Context) (resp *RespLogout, err error)

Logout the current user. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3logout This does not clear the credentials from the client instance. See ClearCredentials() instead.

func (*Client) LogoutAll added in v0.9.0

func (cli *Client) LogoutAll(ctx context.Context) (resp *RespLogout, err error)

LogoutAll logs out all the devices of the current user. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3logoutall This does not clear the credentials from the client instance. See ClearCredentials() instead.

func (*Client) MakeFullRequest added in v0.7.2

func (cli *Client) MakeFullRequest(ctx context.Context, params FullRequest) ([]byte, error)

func (*Client) MakeFullRequestWithResp added in v0.19.0

func (cli *Client) MakeFullRequestWithResp(ctx context.Context, params FullRequest) ([]byte, *http.Response, error)

func (*Client) MakeRequest

func (cli *Client) MakeRequest(ctx context.Context, method string, httpURL string, reqBody any, resBody any) ([]byte, error)

func (*Client) MarkRead

func (cli *Client) MarkRead(ctx context.Context, roomID id.RoomID, eventID id.EventID) (err error)

func (*Client) MarkReadWithContent deprecated added in v0.9.12

func (cli *Client) MarkReadWithContent(ctx context.Context, roomID id.RoomID, eventID id.EventID, content interface{}) (err error)

MarkReadWithContent sends a read receipt including custom data.

Deprecated: Use SendReceipt instead.

func (*Client) Members

func (cli *Client) Members(ctx context.Context, roomID id.RoomID, req ...ReqMembers) (resp *RespMembers, err error)

func (*Client) Messages

func (cli *Client) Messages(ctx context.Context, roomID id.RoomID, from, to string, dir Direction, filter *FilterPart, limit int) (resp *RespMessages, err error)

Messages returns a list of message and state events for a room. It uses pagination query parameters to paginate history in the room. See https://spec.matrix.org/v1.12/client-server-api/#get_matrixclientv3roomsroomidmessages

func (*Client) MoveInviteState added in v0.15.3

func (cli *Client) MoveInviteState(ctx context.Context, resp *RespSync, _ string) bool

MoveInviteState is a sync handler that moves events from the state event list to the InviteRoomState in the invite event.

To use it, register it with your Syncer, e.g.:

cli.Syncer.(mautrix.ExtensibleSyncer).OnSync(cli.MoveInviteState)

func (*Client) PutKeysInBackup added in v0.18.0

func (cli *Client) PutKeysInBackup(ctx context.Context, version id.KeyBackupVersion, req *ReqKeyBackup) (resp *RespRoomKeysUpdate, err error)

PutKeysInBackup stores several keys in the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#put_matrixclientv3room_keyskeys

func (*Client) PutKeysInBackupForRoom added in v0.18.0

func (cli *Client) PutKeysInBackupForRoom(ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID, req *ReqRoomKeyBackup) (resp *RespRoomKeysUpdate, err error)

PutKeysInBackupForRoom stores several keys in the backup for the given room.

See: https://spec.matrix.org/v1.9/client-server-api/#put_matrixclientv3room_keyskeysroomid

func (*Client) PutKeysInBackupForRoomAndSession added in v0.18.0

func (cli *Client) PutKeysInBackupForRoomAndSession(ctx context.Context, version id.KeyBackupVersion, roomID id.RoomID, sessionID id.SessionID, req *ReqKeyBackupData) (resp *RespRoomKeysUpdate, err error)

PutKeysInBackupForRoomAndSession stores a key in the backup.

See: https://spec.matrix.org/v1.9/client-server-api/#put_matrixclientv3room_keyskeysroomidsessionid

func (*Client) PutPushRule added in v0.4.11

func (cli *Client) PutPushRule(ctx context.Context, scope string, kind pushrules.PushRuleType, ruleID string, req *ReqPutPushRule) error

func (*Client) QueryKeys

func (cli *Client) QueryKeys(ctx context.Context, req *ReqQueryKeys) (resp *RespQueryKeys, err error)

func (*Client) RedactEvent

func (cli *Client) RedactEvent(ctx context.Context, roomID id.RoomID, eventID id.EventID, extra ...ReqRedact) (resp *RespSendEvent, err error)

RedactEvent redacts the given event. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidredacteventidtxnid

func (*Client) Register

func (cli *Client) Register(ctx context.Context, req *ReqRegister) (*RespRegister, *RespUserInteractive, error)

Register makes an HTTP request according to https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3register

Registers with kind=user. For kind=guest, see RegisterGuest.

func (*Client) RegisterAvailable added in v0.12.2

func (cli *Client) RegisterAvailable(ctx context.Context, username string) (resp *RespRegisterAvailable, err error)

RegisterAvailable checks if a username is valid and available for registration on the server.

See https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv3registeravailable for more details

This will always return an error if the username isn't available, so checking the actual response struct is generally not necessary. It is still returned for future-proofing. For a simple availability check, just check that the returned error is nil. `errors.Is` can be used to find the exact reason why a username isn't available:

_, err := cli.RegisterAvailable("cat")
if errors.Is(err, mautrix.MUserInUse) {
	// Username is taken
} else if errors.Is(err, mautrix.MInvalidUsername) {
	// Username is not valid
} else if errors.Is(err, mautrix.MExclusive) {
	// Username is reserved for an appservice
} else if errors.Is(err, mautrix.MLimitExceeded) {
	// Too many requests
} else if err != nil {
	// Unknown error
} else {
	// Username is available
}

func (*Client) RegisterDummy

func (cli *Client) RegisterDummy(ctx context.Context, req *ReqRegister) (*RespRegister, error)

RegisterDummy performs m.login.dummy registration according to https://spec.matrix.org/v1.2/client-server-api/#dummy-auth

Only a username and password need to be provided on the ReqRegister struct. Most local/developer homeservers will allow registration this way. If the homeserver does not, an error is returned.

This does not set credentials on the client instance. See SetCredentials() instead.

res, err := cli.RegisterDummy(&mautrix.ReqRegister{
	Username: "alice",
	Password: "wonderland",
})
if err != nil {
	panic(err)
}
token := res.AccessToken

func (*Client) RegisterGuest

func (cli *Client) RegisterGuest(ctx context.Context, req *ReqRegister) (*RespRegister, *RespUserInteractive, error)

RegisterGuest makes an HTTP request according to https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3register with kind=guest.

For kind=user, see Register.

func (*Client) RemoveTag

func (cli *Client) RemoveTag(ctx context.Context, roomID id.RoomID, tag event.RoomTag) (err error)

func (*Client) ReportEvent added in v0.21.0

func (cli *Client) ReportEvent(ctx context.Context, roomID id.RoomID, eventID id.EventID, reason string) error

func (*Client) ReportRoom added in v0.21.0

func (cli *Client) ReportRoom(ctx context.Context, roomID id.RoomID, reason string) error

func (*Client) RequestStart added in v0.15.4

func (cli *Client) RequestStart(req *http.Request)

func (*Client) ResolveAlias

func (cli *Client) ResolveAlias(ctx context.Context, alias id.RoomAlias) (resp *RespAliasResolve, err error)

func (*Client) SendMassagedStateEvent

func (cli *Client) SendMassagedStateEvent(ctx context.Context, roomID id.RoomID, eventType event.Type, stateKey string, contentJSON interface{}, ts int64) (resp *RespSendEvent, err error)

SendMassagedStateEvent sends a state event into a room with a custom timestamp. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey contentJSON should be a pointer to something that can be encoded as JSON using json.Marshal.

func (*Client) SendMessageEvent

func (cli *Client) SendMessageEvent(ctx context.Context, roomID id.RoomID, eventType event.Type, contentJSON interface{}, extra ...ReqSendEvent) (resp *RespSendEvent, err error)

SendMessageEvent sends a message event into a room. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid contentJSON should be a pointer to something that can be encoded as JSON using json.Marshal.

func (*Client) SendNotice

func (cli *Client) SendNotice(ctx context.Context, roomID id.RoomID, text string) (*RespSendEvent, error)

SendNotice sends an m.room.message event into the given room with a msgtype of m.notice See https://spec.matrix.org/v1.2/client-server-api/#mnotice

func (*Client) SendReaction

func (cli *Client) SendReaction(ctx context.Context, roomID id.RoomID, eventID id.EventID, reaction string) (*RespSendEvent, error)

func (*Client) SendReceipt added in v0.12.4

func (cli *Client) SendReceipt(ctx context.Context, roomID id.RoomID, eventID id.EventID, receiptType event.ReceiptType, content interface{}) (err error)

SendReceipt sends a receipt, usually specifically a read receipt.

Passing nil as the content is safe, the library will automatically replace it with an empty JSON object. To mark a message in a specific thread as read, use pass a ReqSendReceipt as the content.

func (*Client) SendStateEvent

func (cli *Client) SendStateEvent(ctx context.Context, roomID id.RoomID, eventType event.Type, stateKey string, contentJSON interface{}, extra ...ReqSendEvent) (resp *RespSendEvent, err error)

SendStateEvent sends a state event into a room. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidstateeventtypestatekey contentJSON should be a pointer to something that can be encoded as JSON using json.Marshal.

func (*Client) SendText

func (cli *Client) SendText(ctx context.Context, roomID id.RoomID, text string) (*RespSendEvent, error)

SendText sends an m.room.message event into the given room with a msgtype of m.text See https://spec.matrix.org/v1.2/client-server-api/#mtext

func (*Client) SendToDevice

func (cli *Client) SendToDevice(ctx context.Context, eventType event.Type, req *ReqSendToDevice) (resp *RespSendToDevice, err error)

func (*Client) SetAccountData added in v0.7.2

func (cli *Client) SetAccountData(ctx context.Context, name string, data interface{}) (err error)

SetAccountData sets the user's account data of this type. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3useruseridaccount_datatype

func (*Client) SetAvatarURL

func (cli *Client) SetAvatarURL(ctx context.Context, url id.ContentURI) (err error)

SetAvatarURL sets the user's avatar URL. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3profileuseridavatar_url

func (*Client) SetBeeperInboxState added in v0.20.0

func (cli *Client) SetBeeperInboxState(ctx context.Context, roomID id.RoomID, content *ReqSetBeeperInboxState) (err error)

func (*Client) SetCredentials deprecated

func (cli *Client) SetCredentials(userID id.UserID, accessToken string)

SetCredentials sets the user ID and access token on this client instance.

Deprecated: use the StoreCredentials field in ReqLogin instead.

func (*Client) SetDeviceInfo added in v0.8.3

func (cli *Client) SetDeviceInfo(ctx context.Context, deviceID id.DeviceID, req *ReqDeviceInfo) error

func (*Client) SetDisplayName

func (cli *Client) SetDisplayName(ctx context.Context, displayName string) (err error)

SetDisplayName sets the user's profile display name. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3profileuseriddisplayname

func (*Client) SetPresence

func (cli *Client) SetPresence(ctx context.Context, status event.Presence) (err error)

func (*Client) SetReadMarkers added in v0.10.11

func (cli *Client) SetReadMarkers(ctx context.Context, roomID id.RoomID, content interface{}) (err error)

func (*Client) SetRoomAccountData added in v0.9.8

func (cli *Client) SetRoomAccountData(ctx context.Context, roomID id.RoomID, name string, data interface{}) (err error)

SetRoomAccountData sets the user's account data of this type in a specific room. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3useruseridroomsroomidaccount_datatype

func (*Client) SetTags deprecated

func (cli *Client) SetTags(ctx context.Context, roomID id.RoomID, tags event.Tags) (err error)

Deprecated: Synapse may not handle setting m.tag directly properly, so you should use the Add/RemoveTag methods instead.

func (*Client) State added in v0.9.29

func (cli *Client) State(ctx context.Context, roomID id.RoomID) (stateMap RoomStateMap, err error)

State gets all state in a room. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidstate

func (*Client) StateAsArray added in v0.21.1

func (cli *Client) StateAsArray(ctx context.Context, roomID id.RoomID) (state []*event.Event, err error)

StateAsArray gets all the state in a room as an array. It does not update the state store. Use State to get the events as a map and also update the state store.

func (*Client) StateEvent

func (cli *Client) StateEvent(ctx context.Context, roomID id.RoomID, eventType event.Type, stateKey string, outContent interface{}) (err error)

StateEvent gets a single state event in a room. It will attempt to JSON unmarshal into the given "outContent" struct with the HTTP response body, or return an error. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidstateeventtypestatekey

func (*Client) StateStoreSyncHandler added in v0.15.0

func (cli *Client) StateStoreSyncHandler(ctx context.Context, evt *event.Event)

StateStoreSyncHandler can be added as an event handler in the syncer to update the state store automatically.

client.Syncer.(mautrix.ExtensibleSyncer).OnEvent(client.StateStoreSyncHandler)

DefaultSyncer.ParseEventContent must also be true for this to work (which it is by default).

func (*Client) StopSync

func (cli *Client) StopSync()

StopSync stops the ongoing sync started by Sync.

func (*Client) Sync

func (cli *Client) Sync() error

Sync starts syncing with the provided Homeserver. If Sync() is called twice then the first sync will be stopped and the error will be nil.

This function will block until a fatal /sync error occurs, so it should almost always be started as a new goroutine. Fatal sync errors can be caused by:

  • The failure to create a filter.
  • Client.Syncer.OnFailedSync returning an error in response to a failed sync.
  • Client.Syncer.ProcessResponse returning an error.

If you wish to continue retrying in spite of these fatal errors, call Sync() again.

func (*Client) SyncRequest

func (cli *Client) SyncRequest(ctx context.Context, timeout int, since, filterID string, fullState bool, setPresence event.Presence) (resp *RespSync, err error)

SyncRequest makes an HTTP request according to https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3sync

func (*Client) SyncWithContext added in v0.9.0

func (cli *Client) SyncWithContext(ctx context.Context) error

func (*Client) TimestampToEvent added in v0.13.0

func (cli *Client) TimestampToEvent(ctx context.Context, roomID id.RoomID, timestamp time.Time, dir Direction) (resp *RespTimestampToEvent, err error)

TimestampToEvent finds the ID of the event closest to the given timestamp.

See https://spec.matrix.org/v1.6/client-server-api/#get_matrixclientv1roomsroomidtimestamp_to_event

func (*Client) TurnServer

func (cli *Client) TurnServer(ctx context.Context) (resp *RespTurnServer, err error)

TurnServer returns turn server details and credentials for the client to use when initiating calls. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3voipturnserver

func (*Client) TxnID

func (cli *Client) TxnID() string

TxnID returns the next transaction ID.

func (*Client) UnbanUser

func (cli *Client) UnbanUser(ctx context.Context, roomID id.RoomID, req *ReqUnbanUser) (resp *RespUnbanUser, err error)

UnbanUser unbans a user from a room. See https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidunban

func (*Client) UpdateKeyBackupVersion added in v0.18.0

func (cli *Client) UpdateKeyBackupVersion(ctx context.Context, version id.KeyBackupVersion, req *ReqRoomKeysVersionUpdate[backup.MegolmAuthData]) error

UpdateKeyBackupVersion updates information about an existing key backup. Only the auth_data can be modified.

See: https://spec.matrix.org/v1.9/client-server-api/#put_matrixclientv3room_keysversionversion

func (*Client) Upload deprecated

func (cli *Client) Upload(ctx context.Context, content io.Reader, contentType string, contentLength int64) (*RespMediaUpload, error)

Upload uploads the given data to the content repository and returns an MXC URI.

Deprecated: UploadMedia should be used instead.

func (*Client) UploadAsync added in v0.15.3

func (cli *Client) UploadAsync(ctx context.Context, req ReqUploadMedia) (*RespCreateMXC, error)

UploadAsync creates a blank content URI with CreateMXC, starts uploading the data in the background and returns the created MXC immediately.

See https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create and https://spec.matrix.org/v1.7/client-server-api/#put_matrixmediav3uploadservernamemediaid

func (*Client) UploadBytes

func (cli *Client) UploadBytes(ctx context.Context, data []byte, contentType string) (*RespMediaUpload, error)

func (*Client) UploadBytesWithName added in v0.5.0

func (cli *Client) UploadBytesWithName(ctx context.Context, data []byte, contentType, fileName string) (*RespMediaUpload, error)

func (*Client) UploadCrossSigningKeys added in v0.8.0

func (cli *Client) UploadCrossSigningKeys(ctx context.Context, keys *UploadCrossSigningKeysReq, uiaCallback UIACallback) error

UploadCrossSigningKeys uploads the given cross-signing keys to the server. Because the endpoint requires user-interactive authentication a callback must be provided that, given the UI auth parameters, produces the required result (or nil to end the flow).

func (*Client) UploadKeys

func (cli *Client) UploadKeys(ctx context.Context, req *ReqUploadKeys) (resp *RespUploadKeys, err error)
func (cli *Client) UploadLink(ctx context.Context, link string) (*RespMediaUpload, error)

UploadLink uploads an HTTP URL and then returns an MXC URI.

func (*Client) UploadMedia added in v0.5.0

func (cli *Client) UploadMedia(ctx context.Context, data ReqUploadMedia) (*RespMediaUpload, error)

UploadMedia uploads the given data to the content repository and returns an MXC URI. See https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav3upload

func (*Client) UploadSignatures added in v0.8.0

func (cli *Client) UploadSignatures(ctx context.Context, req *ReqUploadSignatures) (resp *RespUploadSignatures, err error)

func (*Client) UserTyping

func (cli *Client) UserTyping(ctx context.Context, roomID id.RoomID, typing bool, timeout time.Duration) (resp *RespTyping, err error)

UserTyping sets the typing status of the user. See https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidtypinguserid

func (*Client) Versions

func (cli *Client) Versions(ctx context.Context) (resp *RespVersions, err error)

Versions returns the list of supported Matrix versions on this homeserver. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientversions

func (*Client) Whoami added in v0.3.6

func (cli *Client) Whoami(ctx context.Context) (resp *RespWhoami, err error)

Whoami gets the user ID of the current user. See https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3accountwhoami

type ClientResponseHandler added in v0.9.29

type ClientResponseHandler = func(req *http.Request, res *http.Response, responseJSON interface{}) ([]byte, error)

type ClientURLPath added in v0.11.0

type ClientURLPath []any

func (ClientURLPath) FullPath added in v0.11.0

func (cup ClientURLPath) FullPath() []any

type ClientWellKnown

type ClientWellKnown struct {
	Homeserver     HomeserverInfo     `json:"m.homeserver"`
	IdentityServer IdentityServerInfo `json:"m.identity_server"`
}

func DiscoverClientAPI

func DiscoverClientAPI(ctx context.Context, serverName string) (*ClientWellKnown, error)

DiscoverClientAPI resolves the client API URL from a Matrix server name. Use ParseUserID to extract the server name from a user ID. https://spec.matrix.org/v1.2/client-server-api/#server-discovery

type CrossSigningKeys added in v0.8.0

type CrossSigningKeys struct {
	UserID     id.UserID               `json:"user_id"`
	Usage      []id.CrossSigningUsage  `json:"usage"`
	Keys       map[id.KeyID]id.Ed25519 `json:"keys"`
	Signatures signatures.Signatures   `json:"signatures,omitempty"`
}

func (*CrossSigningKeys) FirstKey added in v0.8.0

func (csk *CrossSigningKeys) FirstKey() id.Ed25519

type CryptoHelper added in v0.15.0

type DefaultSyncer

type DefaultSyncer struct {

	// ParseEventContent determines whether or not event content should be parsed before passing to handlers.
	ParseEventContent bool
	// ParseErrorHandler is called when event.Content.ParseRaw returns an error.
	// If it returns false, the event will not be forwarded to listeners.
	ParseErrorHandler func(evt *event.Event, err error) bool
	// FilterJSON is used when the client starts syncing and doesn't get an existing filter ID from SyncStore's LoadFilterID.
	FilterJSON *Filter
	// contains filtered or unexported fields
}

DefaultSyncer is the default syncing implementation. You can either write your own syncer, or selectively replace parts of this default syncer (e.g. the ProcessResponse method). The default syncer uses the observer pattern to notify callers about incoming events. See DefaultSyncer.OnEventType for more information.

func NewDefaultSyncer

func NewDefaultSyncer() *DefaultSyncer

NewDefaultSyncer returns an instantiated DefaultSyncer

func (*DefaultSyncer) Dispatch added in v0.15.0

func (s *DefaultSyncer) Dispatch(ctx context.Context, evt *event.Event)

func (*DefaultSyncer) GetFilterJSON

func (s *DefaultSyncer) GetFilterJSON(userID id.UserID) *Filter

GetFilterJSON returns a filter with a timeline limit of 50.

func (*DefaultSyncer) OnEvent added in v0.5.0

func (s *DefaultSyncer) OnEvent(callback EventHandler)

func (*DefaultSyncer) OnEventType

func (s *DefaultSyncer) OnEventType(eventType event.Type, callback EventHandler)

OnEventType allows callers to be notified when there are new events for the given event type. There are no duplicate checks.

func (*DefaultSyncer) OnFailedSync

func (s *DefaultSyncer) OnFailedSync(res *RespSync, err error) (time.Duration, error)

OnFailedSync always returns a 10 second wait period between failed /syncs, never a fatal error.

func (*DefaultSyncer) OnSync added in v0.5.0

func (s *DefaultSyncer) OnSync(callback SyncHandler)

func (*DefaultSyncer) ProcessResponse

func (s *DefaultSyncer) ProcessResponse(ctx context.Context, res *RespSync, since string) (err error)

ProcessResponse processes the /sync response in a way suitable for bots. "Suitable for bots" means a stream of unrepeating events. Returns a fatal error if a listener panics.

type DeviceIDList

type DeviceIDList []id.DeviceID

type DeviceKeys

type DeviceKeys struct {
	UserID     id.UserID              `json:"user_id"`
	DeviceID   id.DeviceID            `json:"device_id"`
	Algorithms []id.Algorithm         `json:"algorithms"`
	Keys       KeyMap                 `json:"keys"`
	Signatures signatures.Signatures  `json:"signatures"`
	Unsigned   map[string]interface{} `json:"unsigned,omitempty"`
}

type DeviceKeysRequest

type DeviceKeysRequest map[id.UserID]DeviceIDList

type DeviceLists added in v0.9.15

type DeviceLists struct {
	Changed []id.UserID `json:"changed,omitempty"`
	Left    []id.UserID `json:"left,omitempty"`
}

type Direction added in v0.13.0

type Direction rune
const (
	DirectionForward  Direction = 'f'
	DirectionBackward Direction = 'b'
)

type DispatchableSyncer added in v0.15.0

type DispatchableSyncer interface {
	Dispatch(ctx context.Context, evt *event.Event)
}

type EventFormat

type EventFormat string
const (
	EventFormatClient     EventFormat = "client"
	EventFormatFederation EventFormat = "federation"
)

type EventHandler added in v0.5.0

type EventHandler func(ctx context.Context, evt *event.Event)

EventHandler handles a single event from a sync response.

type ExtensibleSyncer added in v0.5.0

type ExtensibleSyncer interface {
	OnSync(callback SyncHandler)
	OnEvent(callback EventHandler)
	OnEventType(eventType event.Type, callback EventHandler)
}

type Filter

type Filter struct {
	AccountData FilterPart  `json:"account_data,omitempty"`
	EventFields []string    `json:"event_fields,omitempty"`
	EventFormat EventFormat `json:"event_format,omitempty"`
	Presence    FilterPart  `json:"presence,omitempty"`
	Room        RoomFilter  `json:"room,omitempty"`

	BeeperToDevice *FilterPart `json:"com.beeper.to_device,omitempty"`
}

Filter is used by clients to specify how the server should filter responses to e.g. sync requests Specified by: https://spec.matrix.org/v1.2/client-server-api/#filtering

func DefaultFilter

func DefaultFilter() Filter

DefaultFilter returns the default filter used by the Matrix server if no filter is provided in the request

func (*Filter) Validate

func (filter *Filter) Validate() error

Validate checks if the filter contains valid property values

type FilterPart

type FilterPart struct {
	NotRooms    []id.RoomID  `json:"not_rooms,omitempty"`
	Rooms       []id.RoomID  `json:"rooms,omitempty"`
	Limit       int          `json:"limit,omitempty"`
	NotSenders  []id.UserID  `json:"not_senders,omitempty"`
	NotTypes    []event.Type `json:"not_types,omitempty"`
	Senders     []id.UserID  `json:"senders,omitempty"`
	Types       []event.Type `json:"types,omitempty"`
	ContainsURL *bool        `json:"contains_url,omitempty"`

	LazyLoadMembers         bool `json:"lazy_load_members,omitempty"`
	IncludeRedundantMembers bool `json:"include_redundant_members,omitempty"`
}

FilterPart is used to define filtering rules for specific categories of events

func DefaultFilterPart

func DefaultFilterPart() FilterPart

DefaultFilterPart returns the default filter part used by the Matrix server if no filter is provided in the request

type FullRequest added in v0.9.0

type FullRequest struct {
	Method           string
	URL              string
	Headers          http.Header
	RequestJSON      interface{}
	RequestBytes     []byte
	RequestBody      io.Reader
	RequestLength    int64
	ResponseJSON     interface{}
	MaxAttempts      int
	BackoffDuration  time.Duration
	SensitiveContent bool
	Handler          ClientResponseHandler
	DontReadResponse bool
	Logger           *zerolog.Logger
	Client           *http.Client
}

type HTTPError

type HTTPError struct {
	Request      *http.Request
	Response     *http.Response
	ResponseBody string

	WrappedError error
	RespError    *RespError
	Message      string
}

HTTPError An HTTP Error response, which may wrap an underlying native Go Error.

func (HTTPError) Error

func (e HTTPError) Error() string

func (HTTPError) Is added in v0.7.7

func (e HTTPError) Is(err error) bool

func (HTTPError) IsStatus added in v0.7.7

func (e HTTPError) IsStatus(code int) bool

func (HTTPError) Unwrap added in v0.7.5

func (e HTTPError) Unwrap() error

type HomeserverInfo

type HomeserverInfo struct {
	BaseURL string `json:"base_url"`
}

type IdentifierType added in v0.7.1

type IdentifierType string

type IdentityServerInfo

type IdentityServerInfo struct {
	BaseURL string `json:"base_url"`
}

type JoinedMember added in v0.12.0

type JoinedMember struct {
	DisplayName string `json:"display_name,omitempty"`
	AvatarURL   string `json:"avatar_url,omitempty"`
}

type KeyMap

type KeyMap map[id.DeviceKeyID]string

func (KeyMap) GetCurve25519

func (km KeyMap) GetCurve25519(deviceID id.DeviceID) id.Curve25519

func (KeyMap) GetEd25519

func (km KeyMap) GetEd25519(deviceID id.DeviceID) id.Ed25519

type LazyLoadSummary

type LazyLoadSummary struct {
	Heroes             []id.UserID `json:"m.heroes,omitempty"`
	JoinedMemberCount  *int        `json:"m.joined_member_count,omitempty"`
	InvitedMemberCount *int        `json:"m.invited_member_count,omitempty"`
}

type LoginFlow added in v0.10.2

type LoginFlow struct {
	Type AuthType `json:"type"`
}

type MediaURLPath added in v0.11.0

type MediaURLPath []any

func (MediaURLPath) FullPath added in v0.11.0

func (mup MediaURLPath) FullPath() []any

type MemoryStateStore added in v0.15.0

type MemoryStateStore struct {
	Registrations  map[id.UserID]bool                                    `json:"registrations"`
	Members        map[id.RoomID]map[id.UserID]*event.MemberEventContent `json:"memberships"`
	MembersFetched map[id.RoomID]bool                                    `json:"members_fetched"`
	PowerLevels    map[id.RoomID]*event.PowerLevelsEventContent          `json:"power_levels"`
	Encryption     map[id.RoomID]*event.EncryptionEventContent           `json:"encryption"`
	// contains filtered or unexported fields
}

func (*MemoryStateStore) ClearCachedMembers added in v0.15.2

func (store *MemoryStateStore) ClearCachedMembers(_ context.Context, roomID id.RoomID, memberships ...event.Membership) error

func (*MemoryStateStore) FindSharedRooms added in v0.19.0

func (store *MemoryStateStore) FindSharedRooms(ctx context.Context, userID id.UserID) (rooms []id.RoomID, err error)

func (*MemoryStateStore) GetAllMembers added in v0.21.0

func (store *MemoryStateStore) GetAllMembers(ctx context.Context, roomID id.RoomID) (map[id.UserID]*event.MemberEventContent, error)

func (*MemoryStateStore) GetEncryptionEvent added in v0.15.0

func (store *MemoryStateStore) GetEncryptionEvent(_ context.Context, roomID id.RoomID) (*event.EncryptionEventContent, error)

func (*MemoryStateStore) GetMember added in v0.15.0

func (store *MemoryStateStore) GetMember(ctx context.Context, roomID id.RoomID, userID id.UserID) (*event.MemberEventContent, error)

func (*MemoryStateStore) GetMembership added in v0.15.0

func (store *MemoryStateStore) GetMembership(ctx context.Context, roomID id.RoomID, userID id.UserID) (event.Membership, error)

func (*MemoryStateStore) GetPowerLevel added in v0.15.0

func (store *MemoryStateStore) GetPowerLevel(ctx context.Context, roomID id.RoomID, userID id.UserID) (int, error)

func (*MemoryStateStore) GetPowerLevelRequirement added in v0.15.0

func (store *MemoryStateStore) GetPowerLevelRequirement(ctx context.Context, roomID id.RoomID, eventType event.Type) (int, error)

func (*MemoryStateStore) GetPowerLevels added in v0.15.0

func (store *MemoryStateStore) GetPowerLevels(_ context.Context, roomID id.RoomID) (levels *event.PowerLevelsEventContent, err error)

func (*MemoryStateStore) GetRoomJoinedOrInvitedMembers added in v0.15.1

func (store *MemoryStateStore) GetRoomJoinedOrInvitedMembers(ctx context.Context, roomID id.RoomID) ([]id.UserID, error)

func (*MemoryStateStore) GetRoomMembers added in v0.15.0

func (store *MemoryStateStore) GetRoomMembers(_ context.Context, roomID id.RoomID) (map[id.UserID]*event.MemberEventContent, error)

func (*MemoryStateStore) HasFetchedMembers added in v0.21.0

func (store *MemoryStateStore) HasFetchedMembers(ctx context.Context, roomID id.RoomID) (bool, error)

func (*MemoryStateStore) HasPowerLevel added in v0.15.0

func (store *MemoryStateStore) HasPowerLevel(ctx context.Context, roomID id.RoomID, userID id.UserID, eventType event.Type) (bool, error)

func (*MemoryStateStore) IsConfusableName added in v0.20.0

func (store *MemoryStateStore) IsConfusableName(ctx context.Context, roomID id.RoomID, currentUser id.UserID, name string) ([]id.UserID, error)

func (*MemoryStateStore) IsEncrypted added in v0.15.0

func (store *MemoryStateStore) IsEncrypted(ctx context.Context, roomID id.RoomID) (bool, error)

func (*MemoryStateStore) IsInRoom added in v0.15.0

func (store *MemoryStateStore) IsInRoom(ctx context.Context, roomID id.RoomID, userID id.UserID) bool

func (*MemoryStateStore) IsInvited added in v0.15.0

func (store *MemoryStateStore) IsInvited(ctx context.Context, roomID id.RoomID, userID id.UserID) bool

func (*MemoryStateStore) IsMembership added in v0.15.0

func (store *MemoryStateStore) IsMembership(ctx context.Context, roomID id.RoomID, userID id.UserID, allowedMemberships ...event.Membership) bool

func (*MemoryStateStore) IsRegistered added in v0.15.0

func (store *MemoryStateStore) IsRegistered(_ context.Context, userID id.UserID) (bool, error)

func (*MemoryStateStore) MarkMembersFetched added in v0.21.0

func (store *MemoryStateStore) MarkMembersFetched(ctx context.Context, roomID id.RoomID) error

func (*MemoryStateStore) MarkRegistered added in v0.15.0

func (store *MemoryStateStore) MarkRegistered(_ context.Context, userID id.UserID) error

func (*MemoryStateStore) ReplaceCachedMembers added in v0.21.0

func (store *MemoryStateStore) ReplaceCachedMembers(ctx context.Context, roomID id.RoomID, evts []*event.Event, onlyMemberships ...event.Membership) error

func (*MemoryStateStore) SetEncryptionEvent added in v0.15.0

func (store *MemoryStateStore) SetEncryptionEvent(_ context.Context, roomID id.RoomID, content *event.EncryptionEventContent) error

func (*MemoryStateStore) SetMember added in v0.15.0

func (store *MemoryStateStore) SetMember(_ context.Context, roomID id.RoomID, userID id.UserID, member *event.MemberEventContent) error

func (*MemoryStateStore) SetMembership added in v0.15.0

func (store *MemoryStateStore) SetMembership(_ context.Context, roomID id.RoomID, userID id.UserID, membership event.Membership) error

func (*MemoryStateStore) SetPowerLevels added in v0.15.0

func (store *MemoryStateStore) SetPowerLevels(_ context.Context, roomID id.RoomID, levels *event.PowerLevelsEventContent) error

func (*MemoryStateStore) TryGetMember added in v0.15.0

func (store *MemoryStateStore) TryGetMember(_ context.Context, roomID id.RoomID, userID id.UserID) (member *event.MemberEventContent, err error)

type MemorySyncStore added in v0.15.0

type MemorySyncStore struct {
	Filters   map[id.UserID]string
	NextBatch map[id.UserID]string
}

MemorySyncStore implements the Storer interface.

Everything is persisted in-memory as maps. It is not safe to load/save filter IDs or next batch tokens on any goroutine other than the syncing goroutine: the one which called Client.Sync().

func NewMemorySyncStore added in v0.15.0

func NewMemorySyncStore() *MemorySyncStore

NewMemorySyncStore constructs a new MemorySyncStore.

func (*MemorySyncStore) LoadFilterID added in v0.15.0

func (s *MemorySyncStore) LoadFilterID(ctx context.Context, userID id.UserID) (string, error)

LoadFilterID from memory.

func (*MemorySyncStore) LoadNextBatch added in v0.15.0

func (s *MemorySyncStore) LoadNextBatch(ctx context.Context, userID id.UserID) (string, error)

LoadNextBatch from memory.

func (*MemorySyncStore) SaveFilterID added in v0.15.0

func (s *MemorySyncStore) SaveFilterID(ctx context.Context, userID id.UserID, filterID string) error

SaveFilterID to memory.

func (*MemorySyncStore) SaveNextBatch added in v0.15.0

func (s *MemorySyncStore) SaveNextBatch(ctx context.Context, userID id.UserID, nextBatchToken string) error

SaveNextBatch to memory.

type OTKCount added in v0.9.15

type OTKCount struct {
	Curve25519       int `json:"curve25519,omitempty"`
	SignedCurve25519 int `json:"signed_curve25519,omitempty"`

	// For appservice OTK counts only: the user ID in question
	UserID   id.UserID   `json:"-"`
	DeviceID id.DeviceID `json:"-"`
}

type OneTimeKey

type OneTimeKey struct {
	Key        id.Curve25519         `json:"key"`
	Fallback   bool                  `json:"fallback,omitempty"`
	Signatures signatures.Signatures `json:"signatures,omitempty"`
	Unsigned   map[string]any        `json:"unsigned,omitempty"`
	IsSigned   bool                  `json:"-"`

	// Raw data in the one-time key. This must be used for signature verification to ensure unrecognized fields
	// aren't thrown away (because that would invalidate the signature).
	RawData json.RawMessage `json:"-"`
}

func (*OneTimeKey) MarshalJSON

func (otk *OneTimeKey) MarshalJSON() ([]byte, error)

func (*OneTimeKey) UnmarshalJSON

func (otk *OneTimeKey) UnmarshalJSON(data []byte) (err error)

type OneTimeKeysRequest

type OneTimeKeysRequest map[id.UserID]map[id.DeviceID]id.KeyAlgorithm

type PrefixableURLPath added in v0.11.0

type PrefixableURLPath interface {
	FullPath() []any
}

type ReqAliasCreate

type ReqAliasCreate struct {
	RoomID id.RoomID `json:"room_id"`
}

type ReqAppservicePing added in v0.15.0

type ReqAppservicePing struct {
	TxnID string `json:"transaction_id,omitempty"`
}

type ReqBanUser

type ReqBanUser struct {
	Reason string    `json:"reason,omitempty"`
	UserID id.UserID `json:"user_id"`
}

ReqBanUser is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidban

type ReqBatchSend deprecated added in v0.9.30

type ReqBatchSend struct {
	PrevEventID id.EventID `json:"-"`
	BatchID     id.BatchID `json:"-"`

	BeeperNewMessages bool      `json:"-"`
	BeeperMarkReadBy  id.UserID `json:"-"`

	StateEventsAtStart []*event.Event `json:"state_events_at_start"`
	Events             []*event.Event `json:"events"`
}

Deprecated: MSC2716 was abandoned

type ReqBeeperBatchSend added in v0.15.4

type ReqBeeperBatchSend struct {
	// ForwardIfNoMessages should be set to true if the batch should be forward
	// backfilled if there are no messages currently in the room.
	ForwardIfNoMessages bool           `json:"forward_if_no_messages"`
	Forward             bool           `json:"forward"`
	SendNotification    bool           `json:"send_notification"`
	MarkReadBy          id.UserID      `json:"mark_read_by,omitempty"`
	Events              []*event.Event `json:"events"`
}

type ReqBeeperMergeRoom added in v0.12.4

type ReqBeeperMergeRoom struct {
	NewRoom ReqCreateRoom `json:"create"`
	Key     string        `json:"key"`
	Rooms   []id.RoomID   `json:"rooms"`
	User    id.UserID     `json:"user_id"`
}

type ReqBeeperSplitRoom added in v0.12.4

type ReqBeeperSplitRoom struct {
	RoomID id.RoomID `json:"-"`

	Key   string                `json:"key"`
	Parts []BeeperSplitRoomPart `json:"parts"`
}

type ReqClaimKeys

type ReqClaimKeys struct {
	OneTimeKeys OneTimeKeysRequest `json:"one_time_keys"`

	Timeout int64 `json:"timeout,omitempty"`
}

type ReqCreateMXC added in v0.21.0

type ReqCreateMXC struct {
	BeeperUniqueID string
	BeeperRoomID   id.RoomID
}

type ReqCreateRoom

type ReqCreateRoom struct {
	Visibility      string                 `json:"visibility,omitempty"`
	RoomAliasName   string                 `json:"room_alias_name,omitempty"`
	Name            string                 `json:"name,omitempty"`
	Topic           string                 `json:"topic,omitempty"`
	Invite          []id.UserID            `json:"invite,omitempty"`
	Invite3PID      []ReqInvite3PID        `json:"invite_3pid,omitempty"`
	CreationContent map[string]interface{} `json:"creation_content,omitempty"`
	InitialState    []*event.Event         `json:"initial_state,omitempty"`
	Preset          string                 `json:"preset,omitempty"`
	IsDirect        bool                   `json:"is_direct,omitempty"`
	RoomVersion     string                 `json:"room_version,omitempty"`

	PowerLevelOverride *event.PowerLevelsEventContent `json:"power_level_content_override,omitempty"`

	MeowRoomID            id.RoomID   `json:"fi.mau.room_id,omitempty"`
	BeeperInitialMembers  []id.UserID `json:"com.beeper.initial_members,omitempty"`
	BeeperAutoJoinInvites bool        `json:"com.beeper.auto_join_invites,omitempty"`
	BeeperLocalRoomID     id.RoomID   `json:"com.beeper.local_room_id,omitempty"`
	BeeperBridgeName      string      `json:"com.beeper.bridge_name,omitempty"`
	BeeperBridgeAccountID string      `json:"com.beeper.bridge_account_id,omitempty"`
}

ReqCreateRoom is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom

type ReqDeleteDevice added in v0.8.3

type ReqDeleteDevice struct {
	Auth interface{} `json:"auth,omitempty"`
}

ReqDeleteDevice is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#delete_matrixclientv3devicesdeviceid

type ReqDeleteDevices added in v0.8.3

type ReqDeleteDevices struct {
	Devices []id.DeviceID `json:"devices"`
	Auth    interface{}   `json:"auth,omitempty"`
}

ReqDeleteDevices is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3delete_devices

type ReqDeviceInfo added in v0.8.3

type ReqDeviceInfo struct {
	DisplayName string `json:"display_name,omitempty"`
}

ReqDeviceInfo is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3devicesdeviceid

type ReqHierarchy added in v0.12.3

type ReqHierarchy struct {
	// A pagination token from a previous Hierarchy call.
	// If specified, max_depth and suggested_only cannot be changed from the first request.
	From string
	// Limit for the maximum number of rooms to include per response.
	// The server will apply a default value if a limit isn't provided.
	Limit int
	// Limit for how far to go into the space. When reached, no further child rooms will be returned.
	// The server will apply a default value if a max depth isn't provided.
	MaxDepth *int
	// Flag to indicate whether the server should only consider suggested rooms.
	// Suggested rooms are annotated in their m.space.child event contents.
	SuggestedOnly bool
}

ReqHierarchy contains the parameters for https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv1roomsroomidhierarchy

As it's a GET method, there is no JSON body, so this is only query parameters.

func (*ReqHierarchy) Query added in v0.12.3

func (req *ReqHierarchy) Query() map[string]string

type ReqInvite3PID

type ReqInvite3PID struct {
	IDServer string `json:"id_server"`
	Medium   string `json:"medium"`
	Address  string `json:"address"`
}

ReqInvite3PID is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite-1 It is also a JSON object used in https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom

type ReqInviteUser

type ReqInviteUser struct {
	Reason string    `json:"reason,omitempty"`
	UserID id.UserID `json:"user_id"`
}

ReqInviteUser is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite

type ReqKeyBackup added in v0.18.0

type ReqKeyBackup struct {
	Rooms map[id.RoomID]ReqRoomKeyBackup `json:"rooms"`
}

type ReqKeyBackupData added in v0.18.0

type ReqKeyBackupData struct {
	FirstMessageIndex int             `json:"first_message_index"`
	ForwardedCount    int             `json:"forwarded_count"`
	IsVerified        bool            `json:"is_verified"`
	SessionData       json.RawMessage `json:"session_data"`
}

type ReqKeysSignatures added in v0.8.0

type ReqKeysSignatures struct {
	UserID     id.UserID              `json:"user_id"`
	DeviceID   id.DeviceID            `json:"device_id,omitempty"`
	Algorithms []id.Algorithm         `json:"algorithms,omitempty"`
	Usage      []id.CrossSigningUsage `json:"usage,omitempty"`
	Keys       map[id.KeyID]string    `json:"keys"`
	Signatures signatures.Signatures  `json:"signatures"`
}

type ReqKickUser

type ReqKickUser struct {
	Reason string    `json:"reason,omitempty"`
	UserID id.UserID `json:"user_id"`
}

ReqKickUser is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidkick

type ReqLeave added in v0.10.10

type ReqLeave struct {
	Reason string `json:"reason,omitempty"`
}

type ReqLogin

type ReqLogin struct {
	Type                     AuthType       `json:"type"`
	Identifier               UserIdentifier `json:"identifier"`
	Password                 string         `json:"password,omitempty"`
	Token                    string         `json:"token,omitempty"`
	DeviceID                 id.DeviceID    `json:"device_id,omitempty"`
	InitialDeviceDisplayName string         `json:"initial_device_display_name,omitempty"`
	RefreshToken             bool           `json:"refresh_token,omitempty"`

	// Whether or not the returned credentials should be stored in the Client
	StoreCredentials bool `json:"-"`
	// Whether or not the returned .well-known data should update the homeserver URL in the Client
	StoreHomeserverURL bool `json:"-"`
}

ReqLogin is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3login

type ReqMembers

type ReqMembers struct {
	At            string           `json:"at"`
	Membership    event.Membership `json:"membership,omitempty"`
	NotMembership event.Membership `json:"not_membership,omitempty"`
}

type ReqPresence

type ReqPresence struct {
	Presence event.Presence `json:"presence"`
}

type ReqPutPushRule added in v0.4.11

type ReqPutPushRule struct {
	Before string `json:"-"`
	After  string `json:"-"`

	Actions    []pushrules.PushActionType `json:"actions"`
	Conditions []pushrules.PushCondition  `json:"conditions"`
	Pattern    string                     `json:"pattern"`
}

type ReqQueryKeys

type ReqQueryKeys struct {
	DeviceKeys DeviceKeysRequest `json:"device_keys"`
	Timeout    int64             `json:"timeout,omitempty"`
}

type ReqRedact

type ReqRedact struct {
	Reason string
	TxnID  string
	Extra  map[string]interface{}
}

ReqRedact is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidredacteventidtxnid

type ReqRegister

type ReqRegister struct {
	Username                 string      `json:"username,omitempty"`
	Password                 string      `json:"password,omitempty"`
	DeviceID                 id.DeviceID `json:"device_id,omitempty"`
	InitialDeviceDisplayName string      `json:"initial_device_display_name,omitempty"`
	InhibitLogin             bool        `json:"inhibit_login,omitempty"`
	RefreshToken             bool        `json:"refresh_token,omitempty"`
	Auth                     interface{} `json:"auth,omitempty"`

	// Type for registration, only used for appservice user registrations
	// https://spec.matrix.org/v1.2/application-service-api/#server-admin-style-permissions
	Type AuthType `json:"type,omitempty"`
}

ReqRegister is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3register

type ReqReport added in v0.21.0

type ReqReport struct {
	Reason string `json:"reason,omitempty"`
	Score  int    `json:"score,omitempty"`
}

type ReqRoomKeyBackup added in v0.18.0

type ReqRoomKeyBackup struct {
	Sessions map[id.SessionID]ReqKeyBackupData `json:"sessions"`
}

type ReqRoomKeysVersionCreate added in v0.15.0

type ReqRoomKeysVersionCreate[A any] struct {
	Algorithm id.KeyBackupAlgorithm `json:"algorithm"`
	AuthData  A                     `json:"auth_data"`
}

type ReqRoomKeysVersionUpdate added in v0.18.0

type ReqRoomKeysVersionUpdate[A any] struct {
	Algorithm id.KeyBackupAlgorithm `json:"algorithm"`
	AuthData  A                     `json:"auth_data"`
	Version   id.KeyBackupVersion   `json:"version,omitempty"`
}

type ReqSendEvent

type ReqSendEvent struct {
	Timestamp     int64
	TransactionID string

	DontEncrypt bool

	MeowEventID id.EventID
}

type ReqSendReceipt added in v0.12.4

type ReqSendReceipt struct {
	ThreadID string `json:"thread_id,omitempty"`
}

type ReqSendToDevice

type ReqSendToDevice struct {
	Messages map[id.UserID]map[id.DeviceID]*event.Content `json:"messages"`
}

type ReqSetBeeperInboxState added in v0.20.0

type ReqSetBeeperInboxState struct {
	MarkedUnread *bool              `json:"marked_unread,omitempty"`
	Done         *BeeperInboxDone   `json:"done,omitempty"`
	ReadMarkers  *ReqSetReadMarkers `json:"read_markers,omitempty"`
}

type ReqSetReadMarkers added in v0.10.11

type ReqSetReadMarkers struct {
	Read        id.EventID `json:"m.read,omitempty"`
	ReadPrivate id.EventID `json:"m.read.private,omitempty"`
	FullyRead   id.EventID `json:"m.fully_read,omitempty"`

	BeeperReadExtra        interface{} `json:"com.beeper.read.extra,omitempty"`
	BeeperReadPrivateExtra interface{} `json:"com.beeper.read.private.extra,omitempty"`
	BeeperFullyReadExtra   interface{} `json:"com.beeper.fully_read.extra,omitempty"`
}

type ReqSync added in v0.9.25

type ReqSync struct {
	Timeout         int
	Since           string
	FilterID        string
	FullState       bool
	SetPresence     event.Presence
	StreamResponse  bool
	BeeperStreaming bool
	Client          *http.Client
}

func (*ReqSync) BuildQuery added in v0.9.25

func (req *ReqSync) BuildQuery() map[string]string

type ReqTyping

type ReqTyping struct {
	Typing  bool  `json:"typing"`
	Timeout int64 `json:"timeout,omitempty"`
}

ReqTyping is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidtypinguserid

type ReqUIAuthFallback added in v0.8.0

type ReqUIAuthFallback struct {
	Session string `json:"session"`
	User    string `json:"user"`
}

type ReqUIAuthLogin added in v0.8.0

type ReqUIAuthLogin struct {
	BaseAuthData
	User     string `json:"user,omitempty"`
	Password string `json:"password,omitempty"`
	Token    string `json:"token,omitempty"`
}

type ReqUnbanUser

type ReqUnbanUser struct {
	Reason string    `json:"reason,omitempty"`
	UserID id.UserID `json:"user_id"`
}

ReqUnbanUser is the JSON request for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidunban

type ReqUploadKeys

type ReqUploadKeys struct {
	DeviceKeys  *DeviceKeys             `json:"device_keys,omitempty"`
	OneTimeKeys map[id.KeyID]OneTimeKey `json:"one_time_keys,omitempty"`
}

type ReqUploadMedia added in v0.5.0

type ReqUploadMedia struct {
	ContentBytes  []byte
	Content       io.Reader
	ContentLength int64
	ContentType   string
	FileName      string

	DoneCallback func()

	// MXC specifies an existing MXC URI which doesn't have content yet to upload into.
	// See https://spec.matrix.org/unstable/client-server-api/#put_matrixmediav3uploadservernamemediaid
	MXC id.ContentURI

	// UnstableUploadURL specifies the URL to upload the content to. MXC must also be set.
	// see https://github.com/matrix-org/matrix-spec-proposals/pull/3870 for more info
	UnstableUploadURL string
}

type ReqUploadSignatures added in v0.8.0

type ReqUploadSignatures map[id.UserID]map[string]ReqKeysSignatures

type RespAliasCreate

type RespAliasCreate struct{}

type RespAliasDelete

type RespAliasDelete struct{}

type RespAliasList added in v0.11.0

type RespAliasList struct {
	Aliases []id.RoomAlias `json:"aliases"`
}

type RespAliasResolve

type RespAliasResolve struct {
	RoomID  id.RoomID `json:"room_id"`
	Servers []string  `json:"servers"`
}

type RespAppservicePing added in v0.15.0

type RespAppservicePing struct {
	DurationMS int64 `json:"duration_ms"`
}

type RespBanUser

type RespBanUser struct{}

RespBanUser is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidban

type RespBatchSend deprecated added in v0.9.30

type RespBatchSend struct {
	StateEventIDs []id.EventID `json:"state_event_ids"`
	EventIDs      []id.EventID `json:"event_ids"`

	InsertionEventID     id.EventID `json:"insertion_event_id"`
	BatchEventID         id.EventID `json:"batch_event_id"`
	BaseInsertionEventID id.EventID `json:"base_insertion_event_id"`

	NextBatchID id.BatchID `json:"next_batch_id"`
}

Deprecated: MSC2716 was abandoned

type RespBeeperBatchSend added in v0.15.4

type RespBeeperBatchSend struct {
	EventIDs []id.EventID `json:"event_ids"`
}

type RespBeeperMergeRoom added in v0.12.4

type RespBeeperMergeRoom RespCreateRoom

type RespBeeperSplitRoom added in v0.12.4

type RespBeeperSplitRoom struct {
	RoomIDs map[string]id.RoomID `json:"room_ids"`
}

type RespCapabilities added in v0.12.0

type RespCapabilities struct {
	RoomVersions    *CapRoomVersions `json:"m.room_versions,omitempty"`
	ChangePassword  *CapBooleanTrue  `json:"m.change_password,omitempty"`
	SetDisplayname  *CapBooleanTrue  `json:"m.set_displayname,omitempty"`
	SetAvatarURL    *CapBooleanTrue  `json:"m.set_avatar_url,omitempty"`
	ThreePIDChanges *CapBooleanTrue  `json:"m.3pid_changes,omitempty"`

	Custom map[string]interface{} `json:"-"`
}

RespCapabilities is the JSON response for https://spec.matrix.org/v1.3/client-server-api/#get_matrixclientv3capabilities

func (*RespCapabilities) MarshalJSON added in v0.12.0

func (rc *RespCapabilities) MarshalJSON() ([]byte, error)

func (*RespCapabilities) UnmarshalJSON added in v0.12.0

func (rc *RespCapabilities) UnmarshalJSON(data []byte) error

type RespClaimKeys

type RespClaimKeys struct {
	Failures    map[string]interface{}                                `json:"failures,omitempty"`
	OneTimeKeys map[id.UserID]map[id.DeviceID]map[id.KeyID]OneTimeKey `json:"one_time_keys"`
}

type RespContext added in v0.10.9

type RespContext struct {
	End          string         `json:"end"`
	Event        *event.Event   `json:"event"`
	EventsAfter  []*event.Event `json:"events_after"`
	EventsBefore []*event.Event `json:"events_before"`
	Start        string         `json:"start"`
	State        []*event.Event `json:"state"`
}

RespContext is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidcontexteventid

type RespCreateFilter

type RespCreateFilter struct {
	FilterID string `json:"filter_id"`
}

RespCreateFilter is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3useruseridfilter

type RespCreateMXC added in v0.11.0

type RespCreateMXC struct {
	ContentURI      id.ContentURI      `json:"content_uri"`
	UnusedExpiresAt jsontime.UnixMilli `json:"unused_expires_at,omitempty"`

	UnstableUploadURL string `json:"com.beeper.msc3870.upload_url,omitempty"`

	// Beeper extensions for uploading unique media only once
	BeeperUniqueID    string             `json:"com.beeper.unique_id,omitempty"`
	BeeperCompletedAt jsontime.UnixMilli `json:"com.beeper.completed_at,omitempty"`
}

RespCreateMXC is the JSON response for https://spec.matrix.org/v1.7/client-server-api/#post_matrixmediav1create

type RespCreateRoom

type RespCreateRoom struct {
	RoomID id.RoomID `json:"room_id"`
}

RespCreateRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3createroom

type RespDeviceInfo added in v0.8.3

type RespDeviceInfo struct {
	DeviceID    id.DeviceID `json:"device_id"`
	DisplayName string      `json:"display_name"`
	LastSeenIP  string      `json:"last_seen_ip"`
	LastSeenTS  int64       `json:"last_seen_ts"`
}

RespDeviceInfo is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3devicesdeviceid

type RespDevicesInfo added in v0.8.3

type RespDevicesInfo struct {
	Devices []RespDeviceInfo `json:"devices"`
}

RespDevicesInfo is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3devices

type RespError

type RespError struct {
	ErrCode   string
	Err       string
	ExtraData map[string]any

	StatusCode int
}

RespError is the standard JSON error response from Homeservers. It also implements the Golang "error" interface. See https://spec.matrix.org/v1.2/client-server-api/#api-standards

func (RespError) Error

func (e RespError) Error() string

Error returns the errcode and error message.

func (RespError) Is added in v0.7.7

func (e RespError) Is(err error) bool

func (*RespError) MarshalJSON added in v0.7.7

func (e *RespError) MarshalJSON() ([]byte, error)

func (*RespError) UnmarshalJSON added in v0.7.7

func (e *RespError) UnmarshalJSON(data []byte) error

func (RespError) WithMessage added in v0.21.0

func (e RespError) WithMessage(msg string, args ...any) RespError

func (RespError) WithStatus added in v0.21.1

func (e RespError) WithStatus(status int) RespError

func (RespError) Write added in v0.21.0

func (e RespError) Write(w http.ResponseWriter)

type RespForgetRoom

type RespForgetRoom struct{}

RespForgetRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidforget

type RespHierarchy added in v0.12.3

type RespHierarchy struct {
	NextBatch string            `json:"next_batch,omitempty"`
	Rooms     []ChildRoomsChunk `json:"rooms"`
}

RespHierarchy is the JSON response for https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv1roomsroomidhierarchy

type RespInviteUser

type RespInviteUser struct{}

RespInviteUser is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidinvite

type RespJoinRoom

type RespJoinRoom struct {
	RoomID id.RoomID `json:"room_id"`
}

RespJoinRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidjoin

type RespJoinedMembers

type RespJoinedMembers struct {
	Joined map[id.UserID]JoinedMember `json:"joined"`
}

RespJoinedMembers is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidjoined_members

type RespJoinedRooms

type RespJoinedRooms struct {
	JoinedRooms []id.RoomID `json:"joined_rooms"`
}

RespJoinedRooms is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3joined_rooms

type RespKeyBackupData added in v0.18.0

type RespKeyBackupData[S any] struct {
	FirstMessageIndex int  `json:"first_message_index"`
	ForwardedCount    int  `json:"forwarded_count"`
	IsVerified        bool `json:"is_verified"`
	SessionData       S    `json:"session_data"`
}

type RespKeyChanges

type RespKeyChanges struct {
	Changed []id.UserID `json:"changed"`
	Left    []id.UserID `json:"left"`
}

type RespKickUser

type RespKickUser struct{}

RespKickUser is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidkick

type RespLeaveRoom

type RespLeaveRoom struct{}

RespLeaveRoom is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidleave

type RespLogin

type RespLogin struct {
	AccessToken string           `json:"access_token"`
	DeviceID    id.DeviceID      `json:"device_id"`
	UserID      id.UserID        `json:"user_id"`
	WellKnown   *ClientWellKnown `json:"well_known,omitempty"`
}

RespLogin is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3login

type RespLoginFlows

type RespLoginFlows struct {
	Flows []LoginFlow `json:"flows"`
}

RespLoginFlows is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3login

func (*RespLoginFlows) FirstFlowOfType added in v0.10.2

func (rlf *RespLoginFlows) FirstFlowOfType(flowTypes ...AuthType) *LoginFlow

func (*RespLoginFlows) HasFlow added in v0.7.13

func (rlf *RespLoginFlows) HasFlow(flowType ...AuthType) bool

type RespLogout

type RespLogout struct{}

RespLogout is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3logout

type RespMediaConfig added in v0.12.2

type RespMediaConfig struct {
	UploadSize int64 `json:"m.upload.size,omitempty"`
}

RespMediaConfig is the JSON response for https://spec.matrix.org/v1.4/client-server-api/#get_matrixmediav3config

type RespMediaUpload

type RespMediaUpload struct {
	ContentURI id.ContentURI `json:"content_uri"`
}

RespMediaUpload is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixmediav3upload

type RespMembers

type RespMembers struct {
	Chunk []*event.Event `json:"chunk"`
}

type RespMessages

type RespMessages struct {
	Start string         `json:"start"`
	Chunk []*event.Event `json:"chunk"`
	State []*event.Event `json:"state"`
	End   string         `json:"end,omitempty"`
}

RespMessages is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3roomsroomidmessages

type RespPresence added in v0.9.2

type RespPresence struct {
	Presence        event.Presence `json:"presence"`
	LastActiveAgo   int            `json:"last_active_ago"`
	StatusMsg       string         `json:"status_msg"`
	CurrentlyActive bool           `json:"currently_active"`
}

RespPresence is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3presenceuseridstatus

type RespPreviewURL added in v0.10.11

type RespPreviewURL = event.LinkPreview

RespPreviewURL is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixmediav3preview_url

type RespQueryKeys

type RespQueryKeys struct {
	Failures        map[string]interface{}                   `json:"failures,omitempty"`
	DeviceKeys      map[id.UserID]map[id.DeviceID]DeviceKeys `json:"device_keys"`
	MasterKeys      map[id.UserID]CrossSigningKeys           `json:"master_keys"`
	SelfSigningKeys map[id.UserID]CrossSigningKeys           `json:"self_signing_keys"`
	UserSigningKeys map[id.UserID]CrossSigningKeys           `json:"user_signing_keys"`
}

type RespRegister

type RespRegister struct {
	AccessToken string      `json:"access_token,omitempty"`
	DeviceID    id.DeviceID `json:"device_id,omitempty"`
	UserID      id.UserID   `json:"user_id"`

	RefreshToken string `json:"refresh_token,omitempty"`
	ExpiresInMS  int64  `json:"expires_in_ms,omitempty"`

	// Deprecated: homeserver should be parsed from the user ID
	HomeServer string `json:"home_server,omitempty"`
}

RespRegister is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3register

type RespRegisterAvailable added in v0.12.2

type RespRegisterAvailable struct {
	Available bool `json:"available"`
}

RespRegisterAvailable is the JSON response for https://spec.matrix.org/v1.4/client-server-api/#get_matrixclientv3registeravailable

type RespRoomKeyBackup added in v0.18.0

type RespRoomKeyBackup[S any] struct {
	Sessions map[id.SessionID]RespKeyBackupData[S] `json:"sessions"`
}

type RespRoomKeys added in v0.15.0

type RespRoomKeys[S any] struct {
	Rooms map[id.RoomID]RespRoomKeyBackup[S] `json:"rooms"`
}

type RespRoomKeysUpdate added in v0.15.0

type RespRoomKeysUpdate struct {
	Count int    `json:"count"`
	ETag  string `json:"etag"`
}

type RespRoomKeysVersion added in v0.15.0

type RespRoomKeysVersion[A any] struct {
	Algorithm id.KeyBackupAlgorithm `json:"algorithm"`
	AuthData  A                     `json:"auth_data"`
	Count     int                   `json:"count"`
	ETag      string                `json:"etag"`
	Version   id.KeyBackupVersion   `json:"version"`
}

type RespRoomKeysVersionCreate added in v0.15.0

type RespRoomKeysVersionCreate struct {
	Version id.KeyBackupVersion `json:"version"`
}

type RespSendEvent

type RespSendEvent struct {
	EventID id.EventID `json:"event_id"`
}

RespSendEvent is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidsendeventtypetxnid

type RespSendToDevice

type RespSendToDevice struct{}

type RespSync

type RespSync struct {
	NextBatch string `json:"next_batch"`

	AccountData SyncEventsList `json:"account_data"`
	Presence    SyncEventsList `json:"presence"`
	ToDevice    SyncEventsList `json:"to_device"`

	DeviceLists    DeviceLists       `json:"device_lists"`
	DeviceOTKCount OTKCount          `json:"device_one_time_keys_count"`
	FallbackKeys   []id.KeyAlgorithm `json:"device_unused_fallback_key_types"`

	Rooms RespSyncRooms `json:"rooms"`
}

RespSync is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3sync

func (*RespSync) MarshalJSON added in v0.12.0

func (rs *RespSync) MarshalJSON() ([]byte, error)

type RespSyncRooms added in v0.12.0

type RespSyncRooms struct {
	Leave  map[id.RoomID]*SyncLeftRoom    `json:"leave,omitempty"`
	Join   map[id.RoomID]*SyncJoinedRoom  `json:"join,omitempty"`
	Invite map[id.RoomID]*SyncInvitedRoom `json:"invite,omitempty"`
	Knock  map[id.RoomID]*SyncKnockedRoom `json:"knock,omitempty"`
}

type RespTimestampToEvent added in v0.13.0

type RespTimestampToEvent struct {
	EventID   id.EventID         `json:"event_id"`
	Timestamp jsontime.UnixMilli `json:"origin_server_ts"`
}

type RespTurnServer

type RespTurnServer struct {
	Username string   `json:"username"`
	Password string   `json:"password"`
	TTL      int      `json:"ttl"`
	URIs     []string `json:"uris"`
}

type RespTyping

type RespTyping struct{}

RespTyping is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#put_matrixclientv3roomsroomidtypinguserid

type RespUnbanUser

type RespUnbanUser struct{}

RespUnbanUser is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidunban

type RespUploadKeys

type RespUploadKeys struct {
	OneTimeKeyCounts OTKCount `json:"one_time_key_counts"`
}

type RespUploadSignatures added in v0.8.0

type RespUploadSignatures struct {
	Failures map[string]interface{} `json:"failures,omitempty"`
}

type RespUserDisplayName

type RespUserDisplayName struct {
	DisplayName string `json:"displayname"`
}

RespUserDisplayName is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3profileuseriddisplayname

type RespUserInteractive

type RespUserInteractive struct {
	Flows     []UIAFlow                `json:"flows,omitempty"`
	Params    map[AuthType]interface{} `json:"params,omitempty"`
	Session   string                   `json:"session,omitempty"`
	Completed []string                 `json:"completed,omitempty"`

	ErrCode string `json:"errcode,omitempty"`
	Error   string `json:"error,omitempty"`
}

RespUserInteractive is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#user-interactive-authentication-api

func (RespUserInteractive) HasSingleStageFlow

func (r RespUserInteractive) HasSingleStageFlow(stageName AuthType) bool

HasSingleStageFlow returns true if there exists at least 1 Flow with a single stage of stageName.

type RespUserProfile added in v0.12.4

type RespUserProfile struct {
	DisplayName string        `json:"displayname"`
	AvatarURL   id.ContentURI `json:"avatar_url"`
}

type RespVersions

type RespVersions struct {
	Versions         []SpecVersion   `json:"versions"`
	UnstableFeatures map[string]bool `json:"unstable_features"`
}

RespVersions is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientversions

func (*RespVersions) Contains added in v0.11.0

func (versions *RespVersions) Contains(version SpecVersion) bool

func (*RespVersions) ContainsFunc added in v0.11.0

func (versions *RespVersions) ContainsFunc(match func(found SpecVersion) bool) bool

func (*RespVersions) ContainsGreaterOrEqual added in v0.11.0

func (versions *RespVersions) ContainsGreaterOrEqual(version SpecVersion) bool

func (*RespVersions) GetLatest added in v0.12.0

func (versions *RespVersions) GetLatest() (latest SpecVersion)

func (*RespVersions) Supports added in v0.15.4

func (versions *RespVersions) Supports(feature UnstableFeature) bool

type RespWhoami added in v0.3.6

type RespWhoami struct {
	UserID   id.UserID   `json:"user_id"`
	DeviceID id.DeviceID `json:"device_id"`
}

RespWhoami is the JSON response for https://spec.matrix.org/v1.2/client-server-api/#get_matrixclientv3accountwhoami

type Room

type Room struct {
	ID    id.RoomID
	State RoomStateMap
}

Room represents a single Matrix room.

func NewRoom

func NewRoom(roomID id.RoomID) *Room

NewRoom creates a new Room with the given ID

func (Room) GetMembershipState

func (room Room) GetMembershipState(userID id.UserID) event.Membership

GetMembershipState returns the membership state of the given user ID in this room. If there is no entry for this member, 'leave' is returned for consistency with left users.

func (Room) GetStateEvent

func (room Room) GetStateEvent(eventType event.Type, stateKey string) *event.Event

GetStateEvent returns the state event for the given type/state_key combo, or nil.

func (Room) UpdateState

func (room Room) UpdateState(evt *event.Event)

UpdateState updates the room's current state with the given Event. This will clobber events based on the type/state_key combination.

type RoomFilter

type RoomFilter struct {
	AccountData  FilterPart  `json:"account_data,omitempty"`
	Ephemeral    FilterPart  `json:"ephemeral,omitempty"`
	IncludeLeave bool        `json:"include_leave,omitempty"`
	NotRooms     []id.RoomID `json:"not_rooms,omitempty"`
	Rooms        []id.RoomID `json:"rooms,omitempty"`
	State        FilterPart  `json:"state,omitempty"`
	Timeline     FilterPart  `json:"timeline,omitempty"`
}

RoomFilter is used to define filtering rules for room events

type RoomStateMap added in v0.9.29

type RoomStateMap = map[event.Type]map[string]*event.Event

type SpecVersion added in v0.11.0

type SpecVersion struct {
	Format SpecVersionFormat
	Major  int
	Minor  int
	Patch  int

	Raw string
}

func MustParseSpecVersion added in v0.11.0

func MustParseSpecVersion(version string) SpecVersion

func ParseSpecVersion added in v0.11.0

func ParseSpecVersion(version string) (sv SpecVersion, err error)

func (SpecVersion) GreaterThan added in v0.11.0

func (sv SpecVersion) GreaterThan(other SpecVersion) bool

func (SpecVersion) IsEmpty added in v0.15.4

func (sv SpecVersion) IsEmpty() bool

func (SpecVersion) LessThan added in v0.11.0

func (sv SpecVersion) LessThan(other SpecVersion) bool

func (*SpecVersion) MarshalText added in v0.11.0

func (sv *SpecVersion) MarshalText() ([]byte, error)

func (SpecVersion) String added in v0.11.0

func (sv SpecVersion) String() string

func (*SpecVersion) UnmarshalText added in v0.11.0

func (sv *SpecVersion) UnmarshalText(version []byte) error

type SpecVersionFormat added in v0.11.0

type SpecVersionFormat int
const (
	SpecVersionFormatUnknown SpecVersionFormat = iota
	SpecVersionFormatR
	SpecVersionFormatV
)

func (SpecVersionFormat) String added in v0.11.0

func (svf SpecVersionFormat) String() string

type StateStore added in v0.15.0

type StateStore interface {
	IsInRoom(ctx context.Context, roomID id.RoomID, userID id.UserID) bool
	IsInvited(ctx context.Context, roomID id.RoomID, userID id.UserID) bool
	IsMembership(ctx context.Context, roomID id.RoomID, userID id.UserID, allowedMemberships ...event.Membership) bool
	GetMember(ctx context.Context, roomID id.RoomID, userID id.UserID) (*event.MemberEventContent, error)
	TryGetMember(ctx context.Context, roomID id.RoomID, userID id.UserID) (*event.MemberEventContent, error)
	SetMembership(ctx context.Context, roomID id.RoomID, userID id.UserID, membership event.Membership) error
	SetMember(ctx context.Context, roomID id.RoomID, userID id.UserID, member *event.MemberEventContent) error
	IsConfusableName(ctx context.Context, roomID id.RoomID, currentUser id.UserID, name string) ([]id.UserID, error)
	ClearCachedMembers(ctx context.Context, roomID id.RoomID, memberships ...event.Membership) error
	ReplaceCachedMembers(ctx context.Context, roomID id.RoomID, evts []*event.Event, onlyMemberships ...event.Membership) error

	SetPowerLevels(ctx context.Context, roomID id.RoomID, levels *event.PowerLevelsEventContent) error
	GetPowerLevels(ctx context.Context, roomID id.RoomID) (*event.PowerLevelsEventContent, error)

	HasFetchedMembers(ctx context.Context, roomID id.RoomID) (bool, error)
	MarkMembersFetched(ctx context.Context, roomID id.RoomID) error
	GetAllMembers(ctx context.Context, roomID id.RoomID) (map[id.UserID]*event.MemberEventContent, error)

	SetEncryptionEvent(ctx context.Context, roomID id.RoomID, content *event.EncryptionEventContent) error
	IsEncrypted(ctx context.Context, roomID id.RoomID) (bool, error)

	GetRoomJoinedOrInvitedMembers(ctx context.Context, roomID id.RoomID) ([]id.UserID, error)
}

StateStore is an interface for storing basic room state information.

func NewMemoryStateStore added in v0.15.0

func NewMemoryStateStore() StateStore

type StateStoreUpdater added in v0.19.0

type StateStoreUpdater interface {
	UpdateState(ctx context.Context, evt *event.Event)
}

type Storer deprecated

type Storer = SyncStore

Deprecated: renamed to SyncStore

type StrippedStateWithTime added in v0.12.3

type StrippedStateWithTime struct {
	event.StrippedState
	Timestamp jsontime.UnixMilli `json:"origin_server_ts"`
}

type SynapseAdminURLPath added in v0.15.3

type SynapseAdminURLPath []any

func (SynapseAdminURLPath) FullPath added in v0.15.3

func (saup SynapseAdminURLPath) FullPath() []any

type SyncEventsList added in v0.12.0

type SyncEventsList struct {
	Events []*event.Event `json:"events,omitempty"`
}

type SyncHandler added in v0.5.0

type SyncHandler func(ctx context.Context, resp *RespSync, since string) bool

SyncHandler handles a whole sync response. If the return value is false, handling will be stopped completely.

type SyncInvitedRoom

type SyncInvitedRoom struct {
	Summary LazyLoadSummary `json:"summary"`
	State   SyncEventsList  `json:"invite_state"`
}

func (SyncInvitedRoom) MarshalJSON added in v0.12.0

func (sir SyncInvitedRoom) MarshalJSON() ([]byte, error)

type SyncJoinedRoom

type SyncJoinedRoom struct {
	Summary     LazyLoadSummary `json:"summary"`
	State       SyncEventsList  `json:"state"`
	Timeline    SyncTimeline    `json:"timeline"`
	Ephemeral   SyncEventsList  `json:"ephemeral"`
	AccountData SyncEventsList  `json:"account_data"`

	UnreadNotifications *UnreadNotificationCounts `json:"unread_notifications,omitempty"`
	// https://github.com/matrix-org/matrix-spec-proposals/pull/2654
	MSC2654UnreadCount *int `json:"org.matrix.msc2654.unread_count,omitempty"`
	// Beeper extension
	BeeperInboxPreview *BeeperInboxPreviewEvent `json:"com.beeper.inbox.preview,omitempty"`
}

func (SyncJoinedRoom) MarshalJSON added in v0.12.0

func (sjr SyncJoinedRoom) MarshalJSON() ([]byte, error)

type SyncKnockedRoom added in v0.13.0

type SyncKnockedRoom struct {
	State SyncEventsList `json:"knock_state"`
}

type SyncLeftRoom

type SyncLeftRoom struct {
	Summary  LazyLoadSummary `json:"summary"`
	State    SyncEventsList  `json:"state"`
	Timeline SyncTimeline    `json:"timeline"`
}

func (SyncLeftRoom) MarshalJSON added in v0.12.0

func (slr SyncLeftRoom) MarshalJSON() ([]byte, error)

type SyncStore added in v0.15.0

type SyncStore interface {
	SaveFilterID(ctx context.Context, userID id.UserID, filterID string) error
	LoadFilterID(ctx context.Context, userID id.UserID) (string, error)
	SaveNextBatch(ctx context.Context, userID id.UserID, nextBatchToken string) error
	LoadNextBatch(ctx context.Context, userID id.UserID) (string, error)
}

SyncStore is an interface which must be satisfied to store client data.

You can either write a struct which persists this data to disk, or you can use the provided "MemorySyncStore" which just keeps data around in-memory which is lost on restarts.

type SyncTimeline added in v0.12.0

type SyncTimeline struct {
	SyncEventsList
	Limited   bool   `json:"limited,omitempty"`
	PrevBatch string `json:"prev_batch,omitempty"`
}

type Syncer

type Syncer interface {
	// ProcessResponse processes the /sync response. The since parameter is the since= value that was used to produce the response.
	// This is useful for detecting the very first sync (since=""). If an error is return, Syncing will be stopped permanently.
	ProcessResponse(ctx context.Context, resp *RespSync, since string) error
	// OnFailedSync returns either the time to wait before retrying or an error to stop syncing permanently.
	OnFailedSync(res *RespSync, err error) (time.Duration, error)
	// GetFilterJSON for the given user ID. NOT the filter ID.
	GetFilterJSON(userID id.UserID) *Filter
}

Syncer is an interface that must be satisfied in order to do /sync requests on a client.

type UIACallback added in v0.8.0

type UIACallback = func(*RespUserInteractive) interface{}

type UIAFlow added in v0.12.0

type UIAFlow struct {
	Stages []AuthType `json:"stages,omitempty"`
}

type UnreadNotificationCounts added in v0.12.1

type UnreadNotificationCounts struct {
	HighlightCount    int `json:"highlight_count"`
	NotificationCount int `json:"notification_count"`
}

type UnstableFeature added in v0.15.4

type UnstableFeature struct {
	UnstableFlag string
	SpecVersion  SpecVersion
}

type UploadCrossSigningKeysReq added in v0.8.0

type UploadCrossSigningKeysReq struct {
	Master      CrossSigningKeys `json:"master_key"`
	SelfSigning CrossSigningKeys `json:"self_signing_key"`
	UserSigning CrossSigningKeys `json:"user_signing_key"`
	Auth        interface{}      `json:"auth,omitempty"`
}

type UserIdentifier

type UserIdentifier struct {
	Type IdentifierType `json:"type"`

	User string `json:"user,omitempty"`

	Medium  string `json:"medium,omitempty"`
	Address string `json:"address,omitempty"`

	Country string `json:"country,omitempty"`
	Phone   string `json:"phone,omitempty"`
}

type VerificationHelper added in v0.18.0

type VerificationHelper interface {
	// Init initializes the helper. This should be called before any other
	// methods.
	Init(context.Context) error

	// StartVerification starts an interactive verification flow with the given
	// user via a to-device event.
	StartVerification(ctx context.Context, to id.UserID) (id.VerificationTransactionID, error)
	// StartInRoomVerification starts an interactive verification flow with the
	// given user in the given room.
	StartInRoomVerification(ctx context.Context, roomID id.RoomID, to id.UserID) (id.VerificationTransactionID, error)

	// AcceptVerification accepts a verification request.
	AcceptVerification(ctx context.Context, txnID id.VerificationTransactionID) error
	// DismissVerification dismisses a verification request. This will not send
	// a cancellation to the other device. This method should only be called
	// *before* the request has been accepted and will error otherwise.
	DismissVerification(ctx context.Context, txnID id.VerificationTransactionID) error
	// CancelVerification cancels a verification request. This method should
	// only be called *after* the request has been accepted, although it will
	// not error if called beforehand.
	CancelVerification(ctx context.Context, txnID id.VerificationTransactionID, code event.VerificationCancelCode, reason string) error

	// HandleScannedQRData handles the data from a QR code scan.
	HandleScannedQRData(ctx context.Context, data []byte) error
	// ConfirmQRCodeScanned confirms that our QR code has been scanned.
	ConfirmQRCodeScanned(ctx context.Context, txnID id.VerificationTransactionID) error

	// StartSAS starts a SAS verification flow.
	StartSAS(ctx context.Context, txnID id.VerificationTransactionID) error
	// ConfirmSAS indicates that the user has confirmed that the SAS matches
	// SAS shown on the other user's device.
	ConfirmSAS(ctx context.Context, txnID id.VerificationTransactionID) error
}

Directories

Path Synopsis
matrix/mxmain
Package mxmain contains initialization code for a single-network Matrix bridge using the bridgev2 package.
Package mxmain contains initialization code for a single-network Matrix bridge using the bridgev2 package.
networkid
Package networkid contains string types used to represent different kinds of identifiers on remote networks.
Package networkid contains string types used to represent different kinds of identifiers on remote networks.
ed25519
Package ed25519 implements the Ed25519 signature algorithm.
Package ed25519 implements the Ed25519 signature algorithm.
goolm
Package goolm is a pure Go implementation of libolm.
Package goolm is a pure Go implementation of libolm.
goolm/account
account packages an account which stores the identity, one time keys and fallback keys.
account packages an account which stores the identity, one time keys and fallback keys.
goolm/cipher
Package cipher provides the methods and structs to do encryptions for olm/megolm.
Package cipher provides the methods and structs to do encryptions for olm/megolm.
goolm/crypto
Package crpyto provides the nessesary encryption methods for olm/megolm
Package crpyto provides the nessesary encryption methods for olm/megolm
goolm/megolm
megolm provides the ratchet used by the megolm protocol
megolm provides the ratchet used by the megolm protocol
goolm/ratchet
Package ratchet provides the ratchet used by the olm protocol
Package ratchet provides the ratchet used by the olm protocol
goolm/session
Package session provides the different types of sessions for en/decrypting of messages
Package session provides the different types of sessions for en/decrypting of messages
olm
verificationhelper
Package verificationhelper provides a helper for the interactive verification process according to [Section 11.12.2] of the Spec.
Package verificationhelper provides a helper for the interactive verification process according to [Section 11.12.2] of the Spec.
Package format contains utilities for working with Matrix HTML, specifically methods to parse Markdown into HTML and to parse Matrix HTML into text or markdown.
Package format contains utilities for working with Matrix HTML, specifically methods to parse Markdown into HTML and to parse Matrix HTML into text or markdown.
Package pushrules contains utilities to parse push notification rules.
Package pushrules contains utilities to parse push notification rules.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL