feat(onboarding): add notification permission step to setup wizard#19
Merged
Merged
Conversation
User report: "test notifications still fail. i think this is due to
apple permissions and us not having an onboarding for settings enable
permissions."
The wiring was already there — App.tsx calls initNotifications() at
mount, which probes and (if undecided) requests permission. But the
prompt is implicit and easy to dismiss/miss during the chaos of
first-launch (OAuth flows, API key paste, etc.), and once macOS has
recorded a decision it doesn't re-prompt on subsequent launches.
A fresh install that misses the implicit prompt OR has a stale TCC
record from a prior install ends up with notifications=on at the app
level but silently denied at the OS level — exactly the symptom we
hit (UI says "test sent", no banner appears).
This PR makes notification permission an explicit step in the
SetupWizard, between Extensions and Analytics:
- Explains what notifications are for and that macOS decides.
- "Allow notifications" button calls requestPermission() and
surfaces the result inline (granted / denied / dismissed).
- On grant: persists notificationsEnabled=true so the rest of
the app routes through the toggle.
- On denial: shows an "Open System Settings" button that deep-
links to AOS Mail's row in System Settings → Notifications
via x-apple.systempreferences:...?id=com.mrdulasolutions.aosmail
(macOS-recognized since Ventura).
- "Continue without notifications" exit always available —
permission is optional, not a hard gate.
Wires into the existing wizard plumbing: Step type extended with
"permissions"; visibleSteps initialization paths (3) include it
between extensions and analytics; the "no extensions need auth"
skip path now lands on permissions; the Extensions step's
"Continue" button advances to permissions instead of analytics.
After this lands, a fresh-install user with no prior TCC record
will see the macOS notification prompt explicitly inside the
wizard, with surrounding copy explaining why.
Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This was referenced May 13, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
User report: "test notifications still fail. i think this is due to apple permissions and us not having an onboarding for settings enable permissions."
The wiring was always there — App.tsx calls `initNotifications()` at mount, which probes + (if undecided) requests permission. But the macOS prompt arrives implicitly in the middle of first-launch chaos (OAuth flows, API key paste, extensions, etc.), and is easy to miss or dismiss. Once macOS has recorded a decision it doesn't re-prompt on subsequent launches — and a fresh install that misses the implicit prompt OR has a stale TCC record from a prior install ends up with `notificationsEnabled=true` at the app level but silently denied at the OS level.
That's exactly the failure mode we hit: UI says "test sent", no banner appears. `is_permission_granted` returns true (stale record), `notify` returns success, macOS quietly drops the delivery.
What this PR does
Adds an explicit permissions step to the SetupWizard, between Extensions and Analytics.
The step:
Wiring
After this lands
A fresh-install user with no prior TCC record will see the macOS notification prompt explicitly inside the wizard, with surrounding copy explaining why. The bug we hit (stale TCC + no explicit prompt path → silent failure) becomes structurally avoidable.
Combined with the full state-wipe procedure documented in the wiki Troubleshooting page, a user who's hit notification breakage can: nuke → reinstall → wizard prompts cleanly → notifications work.
Test plan
🤖 Generated with Claude Code