# Personal notifications

Bucker has two kinds of notification:

- **Team alerts.** Alert rules page a channel when telemetry crosses a line. They are
  configured under **Alerts** and are described in [alert-rules.md](alert-rules.md).
  Nothing on this page changes them.
- **Personal notifications.** These are about things that happen to you: an approval
  you can decide, an issue assigned to you, an issue you follow regressing. You
  configure them under **Settings › Notifications**.

## What reaches you, and how

Personal notifications use one short, closed list of event types. The inbox is built
from the same list.

| Type | When | Inbox | Email | Slack DM |
| --- | --- | --- | --- | --- |
| `approval_waiting` | An approval you can decide is waiting | on | on | on |
| `assigned` | Someone assigned an issue to you | on | on | on |
| `mention` | Someone mentioned you | on | on | on |
| `watched_regressed` | An issue you participate in regressed | on | on | off |
| `watched_resolved` | Someone else resolved an issue you participate in | on | off | off |
| `remediation_finished` | A remediation you started finished | on | off | off |
| `billing_usage` | Usage, spend and spike notices (owners and billing members) | — | on | — |
| `security_audit` | A security event your organization opted to alert owners on (owners only) | — | on | off |
| `deploy_shipped` | A release carrying commits you wrote was deployed | on | off | off |
| `alert_rule_broken` | An alert rule you own stopped working | on | on | off |
| `budget_breached` | A budget you own was breached | on | on | off |
| `shadow_report_ready` | A shadow-mode report you asked for is ready | on | off | off |
| `receipt_failed` | A receipt for an act you approved or ran failed | on | on | off |
| `fix_still_reported` | A fix you shipped is still being reported after its window | on | off | off |
| `window_ended` | A maintenance, freeze or grant window you opened ended | on | off | off |
| `digest` | Your daily or weekly digest | on | on | off |

The table shows the defaults. Each cell can be turned on or off.

```
GET /me/notifications
PUT /me/notifications   { "changes": [{ "type": "assigned", "channel": "EMAIL", "enabled": false }] }
PUT /me/notifications   { "approvalsBypassQuietHours": true }
```

These are account settings, not org settings. They apply in every organization you
belong to. `billing_usage` is the usage-notice switch that predates the matrix.
`GET/PUT /me/notifications/usage` still work, and they read and write the same cell.

A Slack DM can reach you only after you link your Slack account by running
`/bucker link` in Slack.

`security_audit` is opt-in per organization. An owner chooses which audit actions alert
(`auditAlertActions` on `PATCH /orgs/:orgSlug/security-policy`, from a closed list:
break-glass taken, support access changed, the security policy changed, the allowlist
cleared by an operator, a SCIM or org CI token created, SSO configured or removed, a
member's role changed, a custom role edited, an audit sink removed). The worker reads the
audit log after the fact, so an alert can never fail or slow the action it reports, and
the owner who caused an event is not told about it.

`deploy_shipped` comes from the release's commit list (the commits a release carries,
from its connected repository). A commit is yours when its author email is your account's
email, or when it is GitHub's private form (`<id>+<login>@users.noreply.github.com`) for
the GitHub account you connected under **Connected sign-in accounts**. You are told once
per deploy, however many of the commits are yours, and only by organizations you belong
to. A deploy reported more than a day after it happened is not announced.

### The seven summary notices and their daily caps

The last seven rows above are summaries of things you own. They are capped per person,
per organization and per UTC day, so a rule that flaps cannot fill the bell or your
mailbox:

| Type | Cap per day |
| --- | --- |
| `alert_rule_broken` | 10 |
| `budget_breached` | 5 |
| `shadow_report_ready` | 5 |
| `receipt_failed` | 10 |
| `fix_still_reported` | 5 |
| `window_ended` | 10 |
| `digest` | 1 |

Past the cap the notice is not lost. It is still recorded, but it is not shown in the
inbox and no email or Slack DM is sent. The Summaries section says "N more today", and
your next digest lists those notices. The other types (an approval waiting, an
assignment, a mention) are never capped.

### The digest as a notification

Each recipient gets one `digest` notification per digest: a row in the inbox's
Summaries section, a Slack DM if you turned that cell on (one message with the counts
per section and a link to your inbox), and the full email. The email is sent only when
the deployment has a real mail transport. Where mail is only logged (`EMAIL_PROVIDER=console`)
the email delivery is recorded as skipped with the reason `no_mail_provider` and is never
counted as sent. The digest has an approvals section: pending requests per action family,
the age of the oldest, and how many expire within a day. It carries counts only, never a
request id, plan or token.

## The inbox

The bell in the dashboard header shows how many unread things are waiting on you in
the current organization. It opens your inbox. **Open the inbox page** goes to
`/org/{org}/inbox`, the same list on a full page. The inbox groups rows by what they
need from you:

| Section | Holds |
| --- | --- |
| Waiting on you | Approvals you can decide, while they are still undecided |
| Assigned to you | Issues assigned to you |
| Mentions | Comments that mention you |
| Issues you follow | Regressions and resolutions of issues you participate in |
| Finished | Fix runs you started that have finished, and deploys that shipped your commits |
| Summaries | The seven summary notices and your digest |

- Each row links to the issue or approval it is about. It never holds a copy of the
  conversation.
- Opening a row marks it read. Read state is stored on the server, so it follows you
  to other browsers and devices.
- An approval leaves **Waiting on you** as soon as anyone decides it.
- **Summaries** never counts on the bell. It is the last section, and shows "N more
  today" when notices went past their daily cap.

```
GET  /me/inbox?orgSlug={org}
GET  /me/inbox/count?orgSlug={org}
POST /me/inbox/read   { "orgSlug": "{org}", "ids": ["…"] }   or   { "orgSlug": "{org}", "all": true }
```

The inbox is per person and per organization. Turning off a type's **Inbox** cell in
the matrix keeps that type out of the inbox. Its email and DM still follow their own
cells.

## Issues you participate in

You participate in an issue if any of these is true:

- It is assigned to you. This is read live, so reassigning it moves the notifications too.
- You resolved it.
- You watch it. Use the **Watch** button on the issue page, or call
  `PUT /orgs/{org}/projects/{project}/issues/{issue}/watch { "watching": true }`.
- You commented on it. This one arrives with issue comments.

**Unwatch** stops all of these for that one issue, even when you are its assignee.

Participants get `watched_regressed` when the issue regresses, and `watched_resolved`
when someone else resolves it. The person who caused an event is never notified about
it. For example, someone who assigns an issue to themselves gets no "assigned to you".

Bucker builds these notifications from the records the product already keeps: the
issue's activity, fix runs and approval requests. They arrive however the change was
made, whether from the dashboard, Slack, the API, Jira or the ingest pipeline. Each one
is written once, even if a pass repeats. The sweep runs every minute in the worker. It
appears as `personal-notifications` in the operator console, where it can be paused.

## The weekly digest

Under **Settings › Notifications › Digest** you can choose **Weekly, on Mondays**
(`PUT /me/notifications { "digestCadence": "weekly" }`). You then drop out of the
daily digest and get one email each Monday, per organization you own or administer. It
covers the previous seven days and uses the daily digest's format. Quiet hours delay it
on Monday the same way they delay the daily digest.

## Quiet hours

You set one quiet window, under the digest settings (`PUT /me/digest`). It applies to
the digest and to every personal email and Slack DM:

- A notification that falls inside the window is **held**, not dropped. It is sent
  when the window ends.
- The inbox is never held.
- **Approvals bypass quiet hours** is the one exception, and it is off by default. When
  it is on, approval requests reach you at any hour.
- Team alert rules ignore personal quiet hours. A team decides who it pages.

## Where this is defined

- The vocabulary and defaults: `code/domain/src/modules/notifications/vocabulary.ts`.
- The matrix and the delivery plan: `code/domain/src/modules/notifications/preferences.ts`.
- Participants and the watch: `code/domain/src/modules/notifications/participants.ts`.
- The sources, the fan-out and delivery: `sources.ts`, `fanout.ts` and `delivery.ts` in
  the same directory. The sweep's schedule is `code/workers/src/personal-notifications/`.
- The inbox: `code/domain/src/modules/notifications/inbox.ts`; the bell and the list:
  `code/frontend/src/components/shell/inbox-bell.tsx`, `code/frontend/src/components/inbox/`.
- The hooks for issue comments: `recordCommenter` in `participants.ts` and `notifyMention`
  in `fanout.ts`.
