notifications

type Comms interface {
	RegisterToken(host *connect.Host, message *pb.RegisterTokenRequest) (
		*messages.Ack, error)
	UnregisterToken(host *connect.Host, message *pb.UnregisterTokenRequest) (
		*messages.Ack, error)
	RegisterTrackedID(host *connect.Host,
		message *pb.RegisterTrackedIdRequest) (*messages.Ack, error)
	UnregisterTrackedID(host *connect.Host,
		message *pb.UnregisterTrackedIdRequest) (*messages.Ack, error)
	GetHost(id *id.ID) (*connect.Host, bool)
}

type Group map[id.ID]State

type Manager interface {
	// Set turns notifications on or off for a given ID. It synchronizes the
	// state with all clients and registers with the notification server if
	// status != Mute and a token is set.
	//
	// Group is used to segment the notification lists so that different users
	// of the same object do not interfere. Metadata will be synchronized,
	// allowing more verbose notifications settings. Max 1KB.
	//
	// It returns [ErrInvalidNotificationsState] if the passed in state is
	// invalid.
	//
	// This function, in general, will not be called over the bindings. It will
	// be used by intermediary structures like channels and DMs to provide
	// notification access on a per-case basis.
	//
	// Parameters:
	//   - toBeNotifiedOn - ID that you are tracking. You will receive
	//     notifications that need to be filtered every time a message is
	//     received on this ID.
	//   - group - The group this is categorized in. Used for callbacks and the
	//     GetGroup function to allow for automatic filtering of registered
	//     notifications for a specific submodule or use case. An error is
	//     returned if Set is called on an ID that is already registered at a
	//     different ID.
	//   - metadata - An extra field allowing storage and synchronization of
	//     specific use-case notification data.
	//   - status - The notifications state the ID should be in. These are
	//        Mute - show no notifications for the id
	//        WhenOpen - show notifications only within the open app, no
	//        registration or privacy leak will occur
	//        Push - show notifications as push notification on applicable
	//        devices, will have a minor privacy loss
	Set(toBeNotifiedOn *id.ID, group string, metadata []byte,
		status NotificationState) error

	// Get returns the status of the notifications for the given ID. Returns
	// false if the ID is not registered.
	Get(toBeNotifiedOn *id.ID) (
		status NotificationState, metadata []byte, group string, exists bool)

	// Delete deletes the given ID, unregisters it if it is registered, and
	// removes the reference from the local store.
	Delete(toBeNotifiedOn *id.ID) error

	// SetMaxState sets the maximum functional state of any identity downstream.
	// Modules will be told to clamp any state greater than maxState to
	// maxState.
	//
	// Depending on UX requirements, they may still show the state in an altered
	// manner. For example, greying out a description. This is designed so that
	// when the state is raised, the old configs are maintained.
	//
	// This will unregister/re-register with the push server when leaving or
	// entering the Push maxState. The default maxState Push will return an
	// error if the maxState is not a valid state.
	SetMaxState(maxState NotificationState) error

	// GetMaxState returns the current MaxState.
	GetMaxState() NotificationState

	// GetGroup returns the state of all registered notifications for the given
	// group. If the group is not present, then it returns false.
	GetGroup(group string) (Group, bool)

	// AddToken registers the token with the remote server if this manager is
	// in set to register, otherwise it will return ErrRemoteRegistrationDisabled.
	//
	// This will add the token to the list of tokens that are forwarded the
	// messages for connected IDs. The App will tell the server what app to
	// forward the notifications to.
	AddToken(newToken, app string) error

	// RemoveToken removes the given token from the notification server.
	// It will remove all registered identities if it is the last Token.
	RemoveToken() error

	// GetToken returns the token if it is registered
	GetToken() (has bool, token, app string)

	// RegisterUpdateCallback registers a callback to be used to receive updates
	// to changes in notifications. Because this is being called after
	// initialization, a poll of state via the get function will be necessary
	// because notifications can be missed. You must rely on the data in the
	// callback for the update and not poll the interface. On registration, the
	// callback will be called immediately with all saved IDs as created.
	RegisterUpdateCallback(group string, nu Update)
}

type MockComms struct{}

type NotificationState int64

type State struct {
	Metadata []byte            `json:"metadata"`
	Status   NotificationState `json:"status"`
}

type Update func(group Group, created, edits, deletions []*id.ID,
	maxState NotificationState)