feat(companion): local due-back reminders for checked-out bookings

apps/companion/app.json

@@ -76,6 +76,7 @@
       ],
       "expo-font",
       "expo-web-browser",
+      "expo-notifications",
       "expo-quick-actions",
       "./plugins/swift-concurrency-fix",
       "@sentry/react-native"

apps/companion/app/(tabs)/bookings/[id].tsx

@@ -30,6 +30,7 @@ import {
   type CheckinDisposition,
 } from "@/lib/api";
 import { useOrg } from "@/lib/org-context";
+import { cancelBookingReminders, syncBookingReminders } from "@/lib/reminders";
 import {
   fontSize,
   spacing,
@@ -244,6 +245,11 @@ export default function BookingDetailScreen() {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
+            // Now ONGOING — schedule due-back reminders (interactive: a
+            // direct user action, so the OS permission prompt may show).
+            void syncBookingReminders(booking.id, currentOrg.id, {
+              interactive: true,
+            });
             Alert.alert("Checked Out", `"${booking.name}" is now ongoing.`, [
               { text: "OK", onPress: () => fetchBooking() },
             ]);
@@ -277,6 +283,8 @@ export default function BookingDetailScreen() {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
+            // Fully returned — drop the due-back reminders immediately.
+            void cancelBookingReminders(booking.id);
             Alert.alert("Complete", `"${booking.name}" is now complete.`, [
               {
                 text: "OK",
@@ -317,6 +325,11 @@ export default function BookingDetailScreen() {
     Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
     // Mutation changed this booking — force the list to refetch.
     markBookingsListDirty();
+    // Fully returned → drop reminders now; partial → gear is still out, and
+    // if the due time is unchanged the reminders remain correct as-is.
+    if (data?.isComplete) {
+      void cancelBookingReminders(booking.id);
+    }
     const msg = data?.isComplete
       ? `All assets checked in. "${booking.name}" is now complete.`
       : `${data?.checkedInCount ?? "Some"} checked in, ${
@@ -395,6 +408,12 @@ export default function BookingDetailScreen() {
     Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
     // Mutation changed this booking — force the list to refetch.
     markBookingsListDirty();
+    // The first partial checkout flips RESERVED → ONGOING; sync re-fetches
+    // and only schedules when the booking is genuinely out, so calling it
+    // on every partial success is safe and idempotent.
+    void syncBookingReminders(booking.id, currentOrg.id, {
+      interactive: true,
+    });
     const msg = data?.isComplete
       ? `All assets are now checked out for "${booking.name}".`
       : `${data?.checkedOutCount ?? "Some"} checked out, ${
@@ -546,6 +565,8 @@ export default function BookingDetailScreen() {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
+            // Cancelled bookings have nothing due back.
+            void cancelBookingReminders(booking.id);
             fetchBooking();
           },
         },
@@ -576,6 +597,8 @@ export default function BookingDetailScreen() {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
+            // Archived = administratively closed; stop reminding.
+            void cancelBookingReminders(booking.id);
             fetchBooking();
           },
         },
@@ -607,6 +630,9 @@ export default function BookingDetailScreen() {
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             // Mutation changed this booking — force the list to refetch.
             markBookingsListDirty();
+            // Gone from the server — reminders must go with it (this is why
+            // cancel is fetch-free: a sync would 404 here).
+            void cancelBookingReminders(booking.id);
             // The booking no longer exists — leave the detail screen.
             router.back();
           },

apps/companion/app/(tabs)/scanner.tsx

@@ -21,6 +21,7 @@ import { Ionicons } from "@expo/vector-icons";
 import { api } from "@/lib/api";
 import { useOrg } from "@/lib/org-context";
 import { openShelfWebUrl, pushIntoTab } from "@/lib/navigation";
+import { cancelBookingReminders, syncBookingReminders } from "@/lib/reminders";
 import { TeamMemberPicker } from "@/components/team-member-picker";
 import { LocationPicker } from "@/components/location-picker";
 import type { TeamMember, Location as LocationType } from "@/lib/api";
@@ -1642,6 +1643,13 @@ function ScannerContent() {
               return;
             }
 
+            // Booking is now ONGOING — schedule its due-back reminders.
+            // Interactive: this is a direct user action, so the OS
+            // permission prompt may show here (first checkout only).
+            void syncBookingReminders(bookingId, currentOrg.id, {
+              interactive: true,
+            });
+
             Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success);
             playScanSound();
             Alert.alert(
@@ -1753,6 +1761,12 @@ function ScannerContent() {
                   }
                 : prev
             );
+            // Fully returned → the booking left ONGOING; drop its due-back
+            // reminders immediately (no fetch — we know it closed here).
+            // Partial check-ins keep them: gear is still out.
+            if (result?.isComplete) {
+              void cancelBookingReminders(bookingId);
+            }
             const msg = result?.isComplete
               ? `All assets checked in! "${
                   bookingName || "Booking"

apps/companion/app/(tabs)/settings.tsx

@@ -4,6 +4,7 @@ import {
   Text,
   TouchableOpacity,
   Alert,
+  Linking,
   ScrollView,
   Switch,
 } from "react-native";
@@ -28,6 +29,7 @@ import {
   setScanSoundEnabled,
   playScanSound,
 } from "@/lib/scan-sound";
+import { loadRemindersPreference, setRemindersEnabled } from "@/lib/reminders";
 
 const appVersion =
   Constants.expoConfig?.version ??
@@ -52,11 +54,13 @@ export default function SettingsScreen() {
 
   const [startPage, setStartPageState] = useState<StartPage>("assets");
   const [scanSoundOn, setScanSoundOn] = useState(true);
+  const [remindersOn, setRemindersOn] = useState(true);
 
-  // Load persisted start page and scan sound preference on mount
+  // Load persisted start page, scan sound, and reminders preferences on mount
   useEffect(() => {
     getStartPage().then(setStartPageState);
     loadScanSoundPreference().then(setScanSoundOn);
+    loadRemindersPreference().then(setRemindersOn);
   }, []);
 
   const handleStartPageChange = (page: StartPage) => {
@@ -301,6 +305,60 @@ export default function SettingsScreen() {
         </View>
       </View>
 
+      {/* Booking reminders toggle */}
+      <View style={styles.section}>
+        <Text style={styles.sectionTitle}>Reminders</Text>
+        <View style={styles.card}>
+          <View style={styles.settingRow}>
+            <View style={styles.settingLeft}>
+              <Ionicons
+                name="notifications-outline"
+                size={20}
+                color={colors.foreground}
+              />
+              <View>
+                <Text style={styles.settingLabel}>Booking reminders</Text>
+                <Text style={styles.settingHint}>
+                  Notify when checked-out gear is due back
+                </Text>
+              </View>
+            </View>
+            <Switch
+              value={remindersOn}
+              onValueChange={async (value) => {
+                Haptics.selectionAsync();
+                setRemindersOn(value);
+                // Persists the choice, cancels/reschedules accordingly, and
+                // reports whether the OS-level permission is granted.
+                const granted = await setRemindersEnabled(value);
+                if (value && !granted) {
+                  Alert.alert(
+                    "Notifications are off",
+                    "Shelf can't show reminders until notifications are allowed in your device settings.",
+                    [
+                      { text: "Not now", style: "cancel" },
+                      {
+                        text: "Open Settings",
+                        onPress: () => {
+                          void Linking.openSettings();
+                        },
+                      },
+                    ]
+                  );
+                }
+              }}
+              trackColor={{
+                false: colors.borderLight,
+                true: colors.primary + "60",
+              }}
+              thumbColor={remindersOn ? colors.primary : colors.mutedLight}
+              accessibilityLabel="Toggle booking reminders"
+              accessibilityRole="switch"
+            />
+          </View>
+        </View>
+      </View>
+
       <View style={styles.section}>
         <Text style={styles.sectionTitle}>About</Text>
         <View style={styles.card}>

apps/companion/app/_layout.tsx

@@ -11,6 +11,7 @@ import { OfflineBanner } from "@/components/offline-banner";
 import AnimatedSplash from "@/components/animated-splash";
 import { useDeepLinkHandler } from "@/lib/deep-links";
 import { useQuickActions } from "@/lib/quick-actions";
+import { useBookingReminders } from "@/lib/reminders";
 import { getStartPage, getStartPageRoute } from "@/lib/start-page";
 import { preloadScanSound } from "@/lib/scan-sound";
 import { initSentry } from "@/lib/sentry";
@@ -57,6 +58,10 @@ function RootLayoutNav() {
   // Register 3D Touch / long-press quick actions (home screen shortcuts)
   useQuickActions();
 
+  // Booking due-back reminders: init presentation, reconcile on foreground,
+  // deep-link reminder taps to their booking.
+  useBookingReminders();
+
   // Redirect after splash finishes and auth state is known.
   useEffect(() => {
     if (isLoading || !splashComplete) return;

apps/companion/lib/api/client.ts

@@ -78,12 +78,16 @@ export type ApiFetchOptions = RequestInit & { retry?: boolean };
  * - Returns structured { data, error } -- never throws.
  * - Detects 401/session-expired and notifies global auth listeners.
  * - Enforces a request timeout to avoid hanging on slow networks.
+ * - `status` carries the HTTP status when a response was received at all,
+ *   letting callers tell an authoritative 404/403 ("gone") apart from a
+ *   network/timeout failure (`status` undefined). Additive — existing
+ *   `{ data, error }` destructuring is unaffected.
  */
 export async function apiFetch<T>(
   path: string,
   options: ApiFetchOptions = {},
   _retryCount = 0
-): Promise<{ data: T | null; error: string | null }> {
+): Promise<{ data: T | null; error: string | null; status?: number }> {
   // Declared outside try so catch block can read it
   let timedOut = false;
 
@@ -134,9 +138,17 @@ export async function apiFetch<T>(
       json = text ? JSON.parse(text) : null;
     } catch {
       if (!response.ok) {
-        return { data: null, error: `Server error (${response.status})` };
+        return {
+          data: null,
+          error: `Server error (${response.status})`,
+          status: response.status,
+        };
       }
-      return { data: null, error: "Invalid response from server" };
+      return {
+        data: null,
+        error: "Invalid response from server",
+        status: response.status,
+      };
     }
 
     if (!response.ok) {
@@ -146,6 +158,7 @@ export async function apiFetch<T>(
         return {
           data: null,
           error: "Session expired. Please sign in again.",
+          status: response.status,
         };
       }
       // 403 = forbidden → user lacks permission, but session is valid
@@ -155,15 +168,17 @@ export async function apiFetch<T>(
           error:
             json?.error?.message ||
             "You don't have permission to perform this action.",
+          status: response.status,
         };
       }
       return {
         data: null,
         error: json?.error?.message || `Request failed (${response.status})`,
+        status: response.status,
       };
     }
 
-    return { data: json as T, error: null };
+    return { data: json as T, error: null, status: response.status };
   } catch (err) {
     // Navigation/cleanup abort — silently return null (not an error)
     if (err instanceof Error && err.name === "AbortError" && !timedOut) {

apps/companion/lib/auth-context.tsx

@@ -8,6 +8,10 @@ import {
   type ReactNode,
 } from "react";
 import type { Session, User } from "@supabase/supabase-js";
+// why: deep import — the ./reminders barrel pulls in the org-context-using
+// hook, and org-context imports this file; going straight to the service
+// (which only touches the api client) avoids a require cycle.
+import { clearAllBookingReminders } from "./reminders/service";
 import { supabase } from "./supabase";
 
 type AuthState = {
@@ -58,6 +62,10 @@ export function AuthProvider({ children }: { children: ReactNode }) {
   }, []);
 
   const signOut = useCallback(async () => {
+    // Scheduled booking reminders belong to this account's session. After
+    // sign-out every reconcile fetch would 401 forever, so the tracked
+    // records could never heal — cancel and forget them all up front.
+    await clearAllBookingReminders();
     await supabase.auth.signOut();
   }, []);
 

apps/companion/lib/reminders/index.ts

@@ -0,0 +1,26 @@
+/**
+ * Booking reminders — public surface (consumed exports only).
+ *
+ * Local due-back notifications for bookings checked out from this device:
+ * scheduled on checkout, cancelled on check-in/cancel/archive/delete and
+ * sign-out, and re-derived from the server on every app foreground so they
+ * can never nag about gear that is already back.
+ *
+ * The pure planner and the reconcile/init internals are deliberately NOT
+ * re-exported here — the hook consumes them directly from ./service and
+ * ./plan, and an unused public surface is just dead API to maintain.
+ *
+ * @see {@link file://./plan.ts} pure planner (what fires, when)
+ * @see {@link file://./service.ts} runtime (schedule/cancel/reconcile)
+ * @see {@link file://./use-booking-reminders.ts} app wiring hook
+ */
+export {
+  cancelBookingReminders,
+  loadRemindersPreference,
+  setRemindersEnabled,
+  syncBookingReminders,
+} from "./service";
+export { useBookingReminders } from "./use-booking-reminders";
+// NOTE: clearAllBookingReminders is deliberately not re-exported here — its
+// one consumer (auth-context) deep-imports ./service to avoid a require
+// cycle through the org-context-using hook this barrel pulls in.

apps/companion/lib/reminders/notifications-native.ts

@@ -0,0 +1,44 @@
+/**
+ * Lazy, guarded access to the expo-notifications native module.
+ *
+ * expo-notifications calls `requireNativeModule(...)` at MODULE TOP LEVEL,
+ * so a static `import * as Notifications from "expo-notifications"` crashes
+ * at bundle-evaluation time on any binary built before the module was added
+ * (e.g. a teammate's older dev client pulling this branch, or an OTA update
+ * reaching a pre-notifications build). Call-site try/catch cannot help — the
+ * throw happens before any function runs.
+ *
+ * This wrapper defers the require to first use and memoizes the result, so
+ * builds without the native module degrade to a feature-wide no-op instead
+ * of a startup crash. Type-only imports of expo-notifications are safe
+ * anywhere (erased at compile time); RUNTIME access must go through
+ * {@link getNotifications}.
+ *
+ * @see {@link file://./service.ts} the only intended consumer
+ */
+import type * as ExpoNotifications from "expo-notifications";
+
+/** The full expo-notifications API surface, or null when unavailable. */
+export type NotificationsModule = typeof ExpoNotifications;
+
+/** `undefined` = not yet attempted; `null` = attempted and unavailable. */
+let cached: NotificationsModule | null | undefined;
+
+/**
+ * Load expo-notifications on first use.
+ *
+ * @returns The module, or null when the native side is absent (older build).
+ */
+export function getNotifications(): NotificationsModule | null {
+  if (cached !== undefined) return cached;
+  try {
+    // why: a static import evaluates the package's top-level
+    // requireNativeModule() and crashes pre-notifications builds at startup;
+    // a guarded require is the only way to degrade gracefully.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    cached = require("expo-notifications") as NotificationsModule;
+  } catch {
+    cached = null;
+  }
+  return cached;
+}