notify

type ActorRef struct {
	ID    int64  `json:"id,omitempty"`
	Email string `json:"email,omitempty"`
}

type Bell int

type Config struct {
	WebhookURL   string
	WebhookToken string
	// WebhookLang is the language the legacy webhook's title and body are
	// said in (FILEX_WEBHOOK_LANG); "" is the instance's. A webhook target
	// has its own (model.WebhookTarget.Lang).
	WebhookLang   string
	HTTPTimeout   time.Duration
	RetryBackoffs []time.Duration // attempt delays; default {1s,3s,9s}

	// Digest switches the notification digest on (digest.go). Nil: every
	// notification is told on its own, as before 0.53.
	Digest *DigestConfig
	// Mail sends the emails an event asks for (Event.Mail) and the digest's.
	// Nil: no email.
	Mail MailFunc
	// Push switches Web Push on (push.go): what a person's bell tells them
	// reaches their devices while filex is closed. Nil: no push.
	Push *PushConfig
	// Now is the clock the digest windows are measured with (tests). Nil:
	// time.Now.
	Now func() time.Time
}

type DigestConfig struct {
	// MultiTenant reads a person's defaults from their tenant (scope = its
	// provider id); otherwise from the instance (scope 0).
	MultiTenant bool
	// Every overrides how often the background pass runs (tests).
	Every time.Duration
}

type Digests interface {
	// SetViewer hands in the HTTP layer's View of a person, for the
	// background pass. Without one that pass judges a person's own rows only
	// (their broadcasts are then told on their own, see the file header).
	SetViewer(v Viewer)
	// StartDigests runs the background pass until ctx ends or Stop.
	StartDigests(ctx context.Context)
	// FlushDueDigests runs one background pass now and answers how many
	// digests it wrote.
	FlushDueDigests(ctx context.Context) (int, error)
	// SettleDigest tells userID's held notifications through view if their
	// window has ended — or at once, with force (before their choices
	// change). It answers whether it wrote a digest.
	SettleDigest(ctx context.Context, userID int64, view View, force bool) (bool, error)
	// DigestPolicy is the defaults of one scope as they apply (the built-in
	// ones where nothing was saved), and whether any were saved.
	DigestPolicy(ctx context.Context, scope int64) (model.DigestPolicy, bool, error)
	// SaveDigestPolicy replaces the defaults of p.Scope. The window is
	// clamped to DigestWindowMin..DigestWindowMax; Urgent nil restores the
	// built-in list. Unknown event ids are dropped.
	SaveDigestPolicy(ctx context.Context, p model.DigestPolicy) (model.DigestPolicy, error)
	// PersonDigest is what the settings pane shows a person.
	PersonDigest(ctx context.Context, userID int64) (PersonDigestView, error)
	// DigestScope is which scope a person's defaults are read from.
	DigestScope(ctx context.Context, userID int64) int64
	// ForgetDigest drops what is remembered of a person's choice.
	ForgetDigest(userID int64)
}

type Event struct {
	Event    EventType      `json:"event"`
	Severity Severity       `json:"severity"`
	Title    string         `json:"title"`
	Body     string         `json:"body"`
	Meta     map[string]any `json:"meta,omitempty"`
	TS       time.Time      `json:"ts"`

	// At mirrors TS under the webhook-v2 documented field name; Send
	// fills it from TS so the wire payload always carries `at`.
	At time.Time `json:"at"`

	// Structured webhook-v2 payload objects (all optional). Node points
	// at the file/folder the event concerns, Share at the public link,
	// Actor at the triggering user. Send also folds them into the
	// persisted meta_json so the in-app history keeps the context.
	Node  *NodeRef  `json:"node,omitempty"`
	Share *ShareRef `json:"share,omitempty"`
	Actor *ActorRef `json:"actor,omitempty"`

	// Target is where a click on this notification goes. Emitters set it
	// with FileTarget/DirTarget/ShareTarget/ParentDirTarget; Send fills in
	// the storage NAME from Node.StorageID and, failing that, downgrades the
	// target to TargetNone rather than shipping half an address. It is
	// always non-nil on the wire, so a receiver can switch on `target.kind`
	// without a nil check.
	Target *Target `json:"target,omitempty"`

	// UserID, when non-nil, scopes the in-app notification to a single
	// user. Otherwise the row is broadcast, and who reads it is bell.go's
	// rule: by kind, then — for a member — only when the file it names is one
	// the member can see (handlers/notifications.go). The webhook delivery is
	// unaffected.
	UserID *int64 `json:"-"`

	// NoWebhook keeps the event out of every webhook: the row is stored and
	// read like any other, and its webhook status reads "skipped". For an
	// event addressed to several people one row at a time, where the webhook
	// is told once, with the first row (e2epolicy announce).
	NoWebhook bool `json:"-"`

	// I18n is the event untranslated - the catalogue keys its title and body
	// are said with and their values (say.go Message) - set on a webhook body
	// only, beside the sentence said in the receiver's language.
	I18n *Message `json:"i18n,omitempty"`

	// Mail asks for the addressee (UserID) to be told by email as well. When
	// they hold this kind for their digest (digest.go) the email waits too
	// and comes as the digest's, once for the window; otherwise the words
	// their bell says (say.go) go at once, in their language, the Link under
	// them. Kept in the row's meta (`mail`)
	// so a server that restarts mid-window still knows; never in the webhook
	// body.
	Mail *Mail `json:"-"`
}

type EventType string

type Mail struct {
	// Lang is the addressee's language as the emitter knew it. ⚠ Not what
	// the mail is said in: that is decided at the last stop, from the
	// addressee's account (PersonLang) - an emitter's guess never outranks
	// the person's own setting (#191).
	Lang string `json:"lang,omitempty"`
	// Link is put under the text: where the person acts on it.
	Link string `json:"link,omitempty"`
}

type MailFunc func(ctx context.Context, lang, to, subject, body string) error

type Message struct {
	// Lang is the language Title and Body of the same payload are said in.
	Lang  string       `json:"lang"`
	Title *MessagePart `json:"title,omitempty"`
	// Body is absent where the body is not one phrase - a digest's lines are
	// the phrases its meta lists (groups[].parts, `server.notify.digest.*`).
	Body *MessagePart `json:"body,omitempty"`
}

type MessagePart struct {
	Key   string            `json:"key"`
	Count *int              `json:"count,omitempty"`
	Vars  map[string]string `json:"vars,omitempty"`
}

type NodeRef struct {
	StorageID int64  `json:"storage_id"`
	Path      string `json:"path"`
	Name      string `json:"name"`
	Size      int64  `json:"size,omitempty"`
}

type PersonDigestView struct {
	// WindowMinutes is how long their non-urgent notifications are held.
	WindowMinutes int `json:"window_minutes"`
	// Urgent is the kinds told to them at once: their own choices over the
	// administrator's defaults.
	Urgent []string `json:"urgent_events"`
	// Defaults is the administrator's urgent list, the one a kind they did
	// not choose follows.
	Defaults []string `json:"default_urgent"`
	// Events is every kind a choice can be made about, and AdminEvents the
	// administrator alerts among them (one switch in the pane).
	Events      []string `json:"events"`
	AdminEvents []string `json:"admin_events"`
}

type PushConfig struct {
	// Box seals the VAPID private key (FILEX_SECRET_KEY). Without a key in it
	// push stays off.
	Box *secretbox.Box
	// Subject is the VAPID contact (FILEX_PUSH_SUBJECT): mailto: or https:.
	Subject string
	// Endpoints is which push services a device may name (FILEX_PUSH_HOSTS).
	Endpoints webpush.Policy
	// Client sends the pushes. Nil: webpush.SafeClient.
	Client *http.Client
	// Debounce overrides pushDebounce (tests).
	Debounce time.Duration
}

type PushIcons interface {
	// SetPushIcon sets where a push's icon comes from: the PNG icon the
	// installed app's manifest names for a person's branding (api
	// spa_brand.go), as an address relative to the worker (`<base>/admin/`).
	// Unset, or "" for a person: no icon in the payload, and the worker shows
	// filex's own PNG.
	SetPushIcon(fn func(ctx context.Context, u *model.User) string)
}

type PushInfo struct {
	Available    bool       `json:"available"`
	Reason       string     `json:"reason,omitempty"`
	PublicKey    string     `json:"public_key,omitempty"`
	KeyCreatedAt *time.Time `json:"key_created_at,omitempty"`
}

type PushOff struct{ Reason string }

type PushRefusal struct {
	Code string
	Err  error
}

type PushSubscriptionInput struct {
	Endpoint string
	P256dh   string
	Auth     string
	Label    string
}

type PushTestResult struct {
	Sent   int `json:"sent"`
	Failed int `json:"failed"`
}

type Pushes interface {
	// PushInfo says whether push works here, and with which public key.
	PushInfo(ctx context.Context) PushInfo
	// PushDevices is a person's devices (never their endpoints or keys).
	PushDevices(ctx context.Context, userID int64) ([]*model.PushSubscription, error)
	// PushSubscribe records a device for a person: from now on what their
	// bell tells them is pushed to it. Rows from before are not.
	PushSubscribe(ctx context.Context, userID int64, in PushSubscriptionInput) (*model.PushSubscription, error)
	// PushForget removes one of the person's devices by id; PushForgetEndpoint
	// by its endpoint (the browser turning push off, or signing out). Both
	// answer false for a device that is not theirs.
	PushForget(ctx context.Context, userID, id int64) (bool, error)
	PushForgetEndpoint(ctx context.Context, userID int64, endpoint string) (bool, error)
	// PushTest pushes a test to every device of the person, now.
	PushTest(ctx context.Context, userID int64) (PushTestResult, error)
	// PushCount is how many devices there are, everybody's.
	PushCount(ctx context.Context) (int64, error)
	// RotatePushKey replaces the VAPID key and forgets every device; it
	// answers the new key and how many devices were forgotten.
	RotatePushKey(ctx context.Context) (PushInfo, int64, error)
	// StartPush runs the background pass until ctx ends or Stop.
	StartPush(ctx context.Context)
	// FlushPush runs one pass now over the people woken since the last one
	// and answers how many pushes the push services took.
	FlushPush(ctx context.Context) (int, error)
}

type Said struct {
	// Title and Body are the sentence, in the reader's language, with no
	// encrypted name in them (the lock word stands there).
	Title string
	Body  string
	// Lines is Body one line at a time - a digest's folders, which the bell
	// says on one line ("; ") and an email one under the other.
	Lines []string
	// E2E is where the encrypted names stand, for a reader that can name them;
	// nil when the sentence names none.
	E2E *model.NotificationE2E
}

type Service interface {
	// Send fans the event out to (a) the in-app history table and
	// (b) every configured webhook destination: the legacy global
	// webhook plus each enabled, event-matching webhook_targets row.
	// Errors from webhook delivery are recorded against the row, not
	// bubbled up — webhook failure should never break the originating
	// request.
	Send(ctx context.Context, e Event) (id int64, err error)

	// List + Mark + Settings just delegate to the store; they're on
	// the Service interface so handlers don't have to know about the
	// store. Pass userID nil for admin-global views; bell (which
	// broadcasts a per-user read takes) is ignored there.
	List(ctx context.Context, userID *int64, bell Bell, onlyUnread bool, limit, offset int) ([]*model.Notification, int64, error)
	UnreadCount(ctx context.Context, userID *int64, bell Bell) (int64, error)
	// ListVisible is a per-user read whose BROADCASTS the caller judges one by
	// one after the store (keep — a member's grants, a tenant): the reader's
	// own rows are counted in SQL and only the broadcasts their bell admits are
	// walked, so the total is exact and a page is cut where the reader sees
	// it. keep nil is List. keepOwn, when set, judges the reader's own rows too
	// (a folder-confined token reads only its folder's), walked the same way.
	ListVisible(ctx context.Context, userID int64, bell Bell, onlyUnread bool, limit, offset int, keep, keepOwn func(*model.Notification) bool) ([]*model.Notification, int64, error)
	// History is the admin-global list with each broadcast's read state as
	// readerID has it (0: the rows' own column).
	History(ctx context.Context, readerID int64, onlyUnread bool, limit, offset int) ([]*model.Notification, int64, error)
	// MarkRead and MarkAllRead stamp rows ADDRESSED to userID only. A
	// broadcast is read per reader: MarkBroadcastsRead marks single ones,
	// after the caller has checked the reader may see them, and
	// MarkAllBroadcastsRead reads every broadcast up to now for the reader —
	// ones their bell does not show included, which only ever changes what
	// that reader sees.
	MarkRead(ctx context.Context, id int64, userID *int64) error
	MarkAllRead(ctx context.Context, userID *int64) error
	MarkBroadcastsRead(ctx context.Context, readerID int64, ids []int64) error
	MarkAllBroadcastsRead(ctx context.Context, readerID int64) error
	GetSettings(ctx context.Context, userID int64) (*model.NotificationSettings, error)
	UpsertSettings(ctx context.Context, s *model.NotificationSettings) error

	// SetWebhook is invoked by the admin handler when the operator
	// changes the webhook URL/token at runtime. Pass empty values to
	// disable webhook delivery without taking the in-app channel down.
	SetWebhook(url, bearerToken string)

	// WebhookConfig returns the currently effective webhook URL and a
	// flag indicating whether a token is set (the token itself is
	// never echoed back).
	WebhookConfig() (url string, tokenSet bool)

	// TestTarget synchronously fires a sample event at one webhook
	// target (single attempt, no retries) and returns the outcome.
	// Backs the admin "Test" button; the result is also recorded as
	// the target's in-memory last-delivery status.
	TestTarget(ctx context.Context, target *model.WebhookTarget) TargetDeliveryStatus

	// TargetStatuses returns the last-delivery status per target id.
	// In-memory only (process lifetime) — the schema stays at the
	// frozen webhook_targets contract, so per-target status is not
	// persisted; the notifications table remains the durable audit.
	TargetStatuses() map[int64]TargetDeliveryStatus

	// Wait blocks until any in-flight webhook deliveries return. Used
	// by tests; production calls Stop() instead which cancels the
	// dispatch context AND waits.
	Wait()

	// Stop cancels in-flight dispatches and waits for them to finish.
	Stop()
}

type Severity string

type ShareRef struct {
	Token string `json:"token"`
	Path  string `json:"path,omitempty"`
}

type Target = model.NotificationTarget

type TargetDeliveryStatus struct {
	Status string    `json:"status"` // "sent" | "failed"
	Error  string    `json:"error,omitempty"`
	At     time.Time `json:"at"`
}

type TargetKind = model.NotificationTargetKind

type View struct {
	Bell Bell
	Keep func(*model.Notification) bool
}

type Viewer func(ctx context.Context, userID int64) (View, error)

type WebhookStatus string