notification

type Change struct {
	Action        string // "opened", "closed", "merged", "reopened".
	ChangeTitle   string
	ChangeBody    string // Only set when action is "opened".
	ChangeHTMLURL string
}

type ChangeComment struct {
	ChangeTitle    string
	ChangeState    state.Change
	CommentBody    string
	CommentReview  state.Review
	CommentHTMLURL string
}

type Issue struct {
	Action       string // "opened", "closed", "reopened".
	IssueTitle   string
	IssueBody    string // Only set when action is "opened".
	IssueHTMLURL string
}

type IssueComment struct {
	IssueTitle     string
	IssueState     state.Issue
	CommentBody    string
	CommentHTMLURL string
}

type ListOptions struct {
	// Namespace is an optional filter. If not empty, only notifications
	// from the specified namespace will be listed.
	Namespace string

	// All specifies whether to include read notifications in addition to
	// unread ones.
	All bool
}

type Notification struct {
	Namespace  string
	ThreadType string
	ThreadID   uint64

	ImportPaths []string // 1 or more.
	Time        time.Time
	Actor       users.User

	// Payload specifies the event type. It's one of
	// Issue, Change, IssueComment, or ChangeComment.
	Payload interface{}

	Unread        bool
	Participating bool // Whether user is participating in the thread, or just watching.
	Mentioned     bool // Whether user was specifically @mentioned in the content.
}

type NotificationRequest struct {
	ImportPaths []string  // 1 or more.
	Time        time.Time // Canonical initial time of the notification request.

	// Payload specifies the event type. It's one of
	// Issue, Change, IssueComment, or ChangeComment.
	Payload interface{}
}

type Service interface {
	// ListNotifications lists notifications for authenticated user.
	// A permission error is returned if no authenticated user.
	ListNotifications(ctx context.Context, opt ListOptions) ([]Notification, error)

	// StreamNotifications streams notifications for authenticated user,
	// sending them to ch until context is canceled or an error occurs.
	// A permission error is returned if no authenticated user.
	// TODO: Consider changing signature to single Notification rather than slice, if slice isn't helpful.
	StreamNotifications(ctx context.Context, ch chan<- []Notification) error

	// CountNotifications counts unread notifications for authenticated user.
	// A permission error is returned if no authenticated user.
	CountNotifications(ctx context.Context) (uint64, error)

	// MarkThreadRead marks the specified notification thread as read.
	// A permission error is returned if no authenticated user.
	MarkThreadRead(ctx context.Context, namespace, threadType string, threadID uint64) error

	// SubscribeThread subscribes subscribers to the specified thread.
	// If threadType and threadID are zero, subscribers are subscribed
	// to watch the entire namespace.
	// Returns a permission error if no authenticated user.
	//
	// THINK: Why is MarkRead and MarkAllRead 2 separate methods instead of 1,
	//        but this is combined into one method? Maybe there should be:
	//        SubscribeAll(ctx context.Context, namespace string, subscribers []users.UserSpec) error
	//        Or maybe MarkAllRead should be merged into MarkRead?
	SubscribeThread(ctx context.Context, namespace, threadType string, threadID uint64, subscribers []users.UserSpec) error

	// NotifyThread notifies subscribers of the specified thread of a notification.
	// The authenticated user will be the notification actor.
	// Returns a permission error if no authenticated user.
	NotifyThread(ctx context.Context, namespace, threadType string, threadID uint64, nr NotificationRequest) error
}