Push notification

README.md

@@ -153,6 +153,19 @@ maestro studio
 
 See [`.maestro/README.md`](.maestro/README.md) for detailed E2E testing documentation, troubleshooting, and best practices.
 
+## 🔔 Push Notifications
+
+GuildPass Mobile uses Expo Notifications for real-time updates. Foundation includes:
+
+- **Token Registration**: Device tokens are registered with the backend (mocked in MVP).
+- **Preferences**: Users can opt-in/out of specific notification categories (Role Changes, Access Grants, Membership Status) in Settings.
+- **Permissions**: Automatic permission handling and status reporting.
+
+To test push notifications in development:
+1.  Use a **physical device** (not a simulator).
+2.  Ensure you are logged into your Expo account (`npx expo login`).
+3.  The app will request permissions when first navigating to Settings or performing an action requiring notifications.
+
 ## 🚀 Build & Release
 
 GuildPass Mobile uses **EAS Build** with three distinct profiles:
@@ -237,7 +250,7 @@ Deep links work when the app is cold-started (not already running). The app will
 
 - [ ] **Native Wallet Integration**: Support for WalletConnect, MetaMask, and Coinbase Wallet.
 - [ ] **Smart Onboarding**: Social login and embedded wallets for non-crypto native users.
-- [ ] **Push Notifications**: Real-time alerts for role updates and access grants.
+- [x] **Push Notifications**: Foundation for push notifications with registration and preferences.
 - [x] **QR Access Verification**: Scan GuildPass QR codes to verify token-gated resource access from the mobile app.
 - [ ] **Offline Resilience**: Advanced caching layer for viewing memberships without connectivity.
 

app.json

@@ -82,7 +82,8 @@
         {
           "cameraPermission": "Allow GuildPass to scan access check QR codes."
         }
-      ]
+      ],
+      "expo-notifications"
     ]
   }
 }

app/_layout.tsx

@@ -8,8 +8,14 @@ import { isPersistableQuery, QUERY_GC_TIME_MS } from "../src/lib/offlineCache";
 import "../src/lib/networkManager";
 import { useWalletStore } from "../src/features/wallet/wallet.store";
 import { useSessionStore } from "../src/features/session/session.store";
+import { configureNotifications } from "../src/features/notifications/useNotifications";
 
 export default function RootLayout() {
+  // Configure notification handler and channels once
+  useEffect(() => {
+    configureNotifications();
+  }, []);
+
   // Restore session state from wallet store on cold start
   useEffect(() => {
     const { walletAddress } = useWalletStore.getState();

app/settings.tsx

@@ -6,9 +6,13 @@ import { Button } from "../src/components/Button";
 import { appConfig } from "../src/config/appConfig";
 import { resetAppState } from "../src/lib/resetAppState";
 import React, { useState } from "react";
+import { useNotifications } from "../src/features/notifications/useNotifications";
+import { Toggle } from "../src/components/Toggle";
 
 export default function Settings() {
-  const { isConnected } = useWallet();
+  const { isConnected, address } = useWallet();
+  const { permissionStatus, preferences, requestPermissions, togglePreference, isRegistering } =
+    useNotifications();
   const [isResetting, setIsResetting] = useState(false);
 
   const handleReset = async () => {
@@ -27,6 +31,53 @@ export default function Settings() {
     <View className="flex-1 bg-background" testID="settings-screen">
       <AppHeader title="Settings" showBack />
       <ScrollView className="flex-1 px-4 py-6">
+        <Text className="text-lg font-bold text-text mb-3">Notifications</Text>
+        <Card className="mb-6">
+          <View className="mb-4">
+            <View className="flex-row justify-between items-center mb-2">
+              <Text className="text-text-muted">Push Notifications</Text>
+              <Text
+                className={`font-medium ${
+                  permissionStatus === "granted" ? "text-success" : "text-error"
+                }`}
+                testID="notification-permission-status"
+              >
+                {permissionStatus.charAt(0).toUpperCase() + permissionStatus.slice(1)}
+              </Text>
+            </View>
+            {permissionStatus !== "granted" && (
+              <Button
+                title="Enable Notifications"
+                onPress={requestPermissions}
+                variant="outline"
+                loading={isRegistering}
+                testID="enable-notifications-button"
+              />
+            )}
+          </View>
+
+          <View className="border-t border-border pt-2">
+            <Toggle
+              label="Role Changes"
+              value={preferences.role_changes}
+              onValueChange={() => togglePreference("role_changes", address)}
+              testID="toggle-role-changes"
+            />
+            <Toggle
+              label="Access Grants"
+              value={preferences.access_grants}
+              onValueChange={() => togglePreference("access_grants", address)}
+              testID="toggle-access-grants"
+            />
+            <Toggle
+              label="Membership Status"
+              value={preferences.membership_updates}
+              onValueChange={() => togglePreference("membership_updates", address)}
+              testID="toggle-membership-updates"
+            />
+          </View>
+        </Card>
+
         <Text className="text-lg font-bold text-text mb-3">Protocol Configuration</Text>
         <Card className="mb-6">
           <View className="flex-row justify-between py-2 border-b border-border">