fix(sync): don't crash when IndexedDB is unavailable (PHP-LARAVEL-43) (#654)

## Problem (Sentry PHP-LARAVEL-43)

`ReferenceError: Can't find variable: indexedDB` — an unhandled promise
rejection reported from production. Some browsers do not expose the
global `indexedDB` at all (Chrome on iOS in certain webviews,
private/locked-down modes). The app uses Dexie (IndexedDB) as an offline
cache for transactions, and any Dexie operation in that context throws.

Reproduced entry point: on `/register`, submitting the form runs
`transactionSyncService.clearAll()` → `db.transactions.clear()` → Dexie
references the missing global → throws. The same class of crash can fire
from every other cache touch point (`sync`, `getAll`, `getById`,
`getByAccountId`, and the cache eviction in `delete`).

IndexedDB here is only a cache — the API/Inertia is the source of truth
— so a missing store must degrade to "no local cache", never crash.

## Fix (3 commits)

1. **Guard helper** — `isIndexedDbAvailable()` (checked via `globalThis`
so referencing the global never throws) and `withDb(operation,
fallback)` in `dexie-db.ts`. `withDb` returns the fallback when
IndexedDB is missing or the op fails, and defers `db` access into a
closure so the lazy Dexie proxy never initializes on unsupported
browsers.
2. **Sync manager** — every Dexie read/write goes through `withDb`
(reads → empty, writes/`clearAll` → no-op); `sync()` early-returns a
skipped result and avoids the pointless server round-trip.
3. **Delete eviction** — only the best-effort local cache eviction in
`delete()` is guarded; the authoritative `axios.delete` stays outside
the guard so no API mutation is ever swallowed.

## Safety / complexity

- **No behavior change for browsers with IndexedDB** — `withDb` runs the
operation exactly as before (covered by tests).
- **Graceful degradation otherwise** — no crash; the app runs
online-only.
- **No swallowed mutations** — the guard wraps only Dexie calls; all
`axios` calls stay outside it.
- Reviewed by two agents: the crash does not actually block registration
(Inertia does not await `onBefore`), so this is a recurring unhandled
rejection rather than a hard block, and the fix has no user-facing
downside. Low complexity, high confidence → auto-merge.

## Testing

- New `resources/js/lib/sync-manager.test.ts` and
`resources/js/services/transaction-sync.test.ts` (7 tests): IndexedDB
missing → clearAll/sync/reads/delete-eviction no-op and never throw;
IndexedDB present → unchanged behavior.
- `bun run lint` / `bun run format` clean on the changed files. (The
repo's `tsc --noEmit` has pre-existing errors that CI intentionally does
not gate on; no new ones introduced.)

Fixes PHP-LARAVEL-43

---
🤖 Opened by the autonomous Sentry-triage loop. Auto-merge enabled:
additive guard, no behavior change for supported browsers, no data-loss
surface.

resources/js/lib/dexie-db.ts

@@ -103,3 +103,47 @@ export const db = new Proxy({} as WhisperMoneyDB, {
         return dbInstance[prop as keyof WhisperMoneyDB];
     },
 });
+
+/**
+ * Whether IndexedDB is usable in the current context. Some browsers do not
+ * expose the `indexedDB` global at all — Chrome on iOS in certain webviews,
+ * private/locked-down modes — so any Dexie operation throws
+ * "ReferenceError: Can't find variable: indexedDB" (see PHP-LARAVEL-43). Checked
+ * via `globalThis` so referencing the global never throws, and wrapped
+ * defensively against exotic throwing getters.
+ */
+export function isIndexedDbAvailable(): boolean {
+    try {
+        return (
+            typeof globalThis.indexedDB !== 'undefined' &&
+            globalThis.indexedDB !== null
+        );
+    } catch {
+        return false;
+    }
+}
+
+/**
+ * Run a Dexie operation, degrading to `fallback` when IndexedDB is unavailable
+ * or the operation fails. IndexedDB is only an offline cache here (the API is
+ * the source of truth), so a missing or broken store must never crash the app —
+ * it just means no local cache. Pass ONLY Dexie work in `operation`; keep API
+ * calls outside so they always run. The closure defers `db` access (which lazily
+ * opens Dexie) until after the availability check passes.
+ */
+export async function withDb<T>(
+    operation: () => Promise<T>,
+    fallback: T,
+): Promise<T> {
+    if (!isIndexedDbAvailable()) {
+        return fallback;
+    }
+
+    try {
+        return await operation();
+    } catch (error) {
+        console.debug('IndexedDB operation failed; using fallback', error);
+
+        return fallback;
+    }
+}

resources/js/lib/sync-manager.test.ts

@@ -0,0 +1,103 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { TransactionSyncManager } from './sync-manager';
+
+const dbMock = vi.hoisted(() => ({
+    transactions: {
+        toArray: vi.fn(),
+        get: vi.fn(),
+        clear: vi.fn(),
+        bulkPut: vi.fn(),
+        where: vi.fn(() => ({
+            equals: () => ({ toArray: vi.fn(async () => []) }),
+        })),
+    },
+    sync_metadata: {
+        get: vi.fn(),
+        put: vi.fn(),
+        delete: vi.fn(),
+    },
+}));
+
+// Keep the real isIndexedDbAvailable + withDb (they read globalThis live); only
+// swap the Dexie-backed `db` for spies so no real IndexedDB is needed.
+vi.mock('./dexie-db', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('./dexie-db')>();
+    return { ...actual, db: dbMock };
+});
+
+vi.mock('axios', () => ({ default: { get: vi.fn() } }));
+
+function makeManager(): TransactionSyncManager {
+    return new TransactionSyncManager({ endpoint: '/api/sync/transactions' });
+}
+
+describe('TransactionSyncManager without IndexedDB', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.stubGlobal('indexedDB', undefined);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('clearAll resolves without touching the database or throwing', async () => {
+        await expect(makeManager().clearAll()).resolves.toBeUndefined();
+        expect(dbMock.transactions.clear).not.toHaveBeenCalled();
+        expect(dbMock.sync_metadata.delete).not.toHaveBeenCalled();
+    });
+
+    it('sync returns a skipped result without a server round-trip', async () => {
+        const axios = (await import('axios')).default;
+
+        const result = await makeManager().sync();
+
+        expect(result).toEqual({
+            success: true,
+            inserted: 0,
+            updated: 0,
+            errors: [],
+        });
+        expect(axios.get).not.toHaveBeenCalled();
+    });
+
+    it('reads degrade to empty values instead of throwing', async () => {
+        const manager = makeManager();
+
+        await expect(manager.getAll()).resolves.toEqual([]);
+        await expect(manager.getById('id-1')).resolves.toBeNull();
+        await expect(manager.getByAccountId('acc-1')).resolves.toEqual([]);
+        await expect(manager.getLastSyncTime()).resolves.toBeNull();
+        await expect(manager.setLastSyncTime('now')).resolves.toBeUndefined();
+
+        expect(dbMock.transactions.toArray).not.toHaveBeenCalled();
+        expect(dbMock.sync_metadata.get).not.toHaveBeenCalled();
+    });
+});
+
+describe('TransactionSyncManager with IndexedDB', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+        vi.stubGlobal('indexedDB', {} as IDBFactory);
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('clearAll clears the transactions and sync metadata', async () => {
+        await makeManager().clearAll();
+
+        expect(dbMock.transactions.clear).toHaveBeenCalledTimes(1);
+        expect(dbMock.sync_metadata.delete).toHaveBeenCalledWith(
+            'last_sync_transactions',
+        );
+    });
+
+    it('getAll passes through the stored transactions', async () => {
+        const stored = [{ id: 't1' }];
+        dbMock.transactions.toArray.mockResolvedValueOnce(stored);
+
+        await expect(makeManager().getAll()).resolves.toBe(stored);
+    });
+});

resources/js/lib/sync-manager.ts

@@ -2,7 +2,7 @@ import type { Transaction } from '@/types/transaction';
 import type { UUID } from '@/types/uuid';
 import { __ } from '@/utils/i18n';
 import axios from 'axios';
-import { db } from './dexie-db';
+import { db, isIndexedDbAvailable, withDb } from './dexie-db';
 
 export interface SyncResult {
     success: boolean;
@@ -29,18 +29,29 @@ export class TransactionSyncManager {
     }
 
     async getLastSyncTime(): Promise<string | null> {
-        const metadata = await db.sync_metadata.get(LAST_SYNC_KEY);
-        return metadata?.value || null;
+        return withDb(async () => {
+            const metadata = await db.sync_metadata.get(LAST_SYNC_KEY);
+            return metadata?.value || null;
+        }, null);
     }
 
     async setLastSyncTime(timestamp: string): Promise<void> {
-        await db.sync_metadata.put({
-            key: LAST_SYNC_KEY,
-            value: timestamp,
-        });
+        await withDb<void>(async () => {
+            await db.sync_metadata.put({
+                key: LAST_SYNC_KEY,
+                value: timestamp,
+            });
+        }, undefined);
     }
 
     async sync(): Promise<SyncResult> {
+        // No offline store to sync into (see PHP-LARAVEL-43). Skip cleanly —
+        // empty errors so callers do not treat it as a failure — and avoid the
+        // pointless server round-trip that would only populate a missing cache.
+        if (!isIndexedDbAvailable()) {
+            return { success: true, inserted: 0, updated: 0, errors: [] };
+        }
+
         if (this.syncInProgress) {
             return {
                 success: false,
@@ -129,18 +140,22 @@ export class TransactionSyncManager {
     }
 
     async getAll(): Promise<Transaction[]> {
-        return await db.transactions.toArray();
+        return withDb<Transaction[]>(() => db.transactions.toArray(), []);
     }
 
     async getById(id: UUID): Promise<Transaction | null> {
-        return (await db.transactions.get(id)) || null;
+        return withDb<Transaction | null>(
+            async () => (await db.transactions.get(id)) || null,
+            null,
+        );
     }
 
     async getByAccountId(accountId: UUID): Promise<Transaction[]> {
-        return await db.transactions
-            .where('account_id')
-            .equals(accountId)
-            .toArray();
+        return withDb<Transaction[]>(
+            () =>
+                db.transactions.where('account_id').equals(accountId).toArray(),
+            [],
+        );
     }
 
     isSyncing(): boolean {
@@ -148,7 +163,9 @@ export class TransactionSyncManager {
     }
 
     async clearAll(): Promise<void> {
-        await db.transactions.clear();
-        await db.sync_metadata.delete(LAST_SYNC_KEY);
+        await withDb<void>(async () => {
+            await db.transactions.clear();
+            await db.sync_metadata.delete(LAST_SYNC_KEY);
+        }, undefined);
     }
 }

resources/js/services/transaction-sync.test.ts

@@ -0,0 +1,55 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { transactionSyncService } from './transaction-sync';
+
+const dbMock = vi.hoisted(() => ({
+    transactions: {
+        delete: vi.fn(async () => undefined),
+    },
+    sync_metadata: { delete: vi.fn(), get: vi.fn(), put: vi.fn() },
+}));
+
+const axiosMock = vi.hoisted(() => ({
+    delete: vi.fn(async () => ({ data: {} })),
+}));
+
+// Keep the real withDb (reads globalThis live); swap only the Dexie-backed db.
+vi.mock('@/lib/dexie-db', async (importOriginal) => {
+    const actual = await importOriginal<typeof import('@/lib/dexie-db')>();
+    return { ...actual, db: dbMock };
+});
+
+vi.mock('axios', () => ({ default: axiosMock }));
+
+describe('transactionSyncService.delete', () => {
+    beforeEach(() => {
+        vi.clearAllMocks();
+    });
+
+    afterEach(() => {
+        vi.unstubAllGlobals();
+    });
+
+    it('deletes via the API but skips the cache eviction when IndexedDB is missing', async () => {
+        vi.stubGlobal('indexedDB', undefined);
+
+        await expect(
+            transactionSyncService.delete('txn-1'),
+        ).resolves.toBeUndefined();
+
+        expect(axiosMock.delete).toHaveBeenCalledWith('/transactions/txn-1', {
+            data: undefined,
+        });
+        expect(dbMock.transactions.delete).not.toHaveBeenCalled();
+    });
+
+    it('deletes via the API and evicts the cache when IndexedDB is available', async () => {
+        vi.stubGlobal('indexedDB', {} as IDBFactory);
+
+        await transactionSyncService.delete('txn-1');
+
+        expect(axiosMock.delete).toHaveBeenCalledWith('/transactions/txn-1', {
+            data: undefined,
+        });
+        expect(dbMock.transactions.delete).toHaveBeenCalledWith('txn-1');
+    });
+});

resources/js/services/transaction-sync.ts

@@ -1,4 +1,4 @@
-import { db } from '@/lib/dexie-db';
+import { db, withDb } from '@/lib/dexie-db';
 import { TransactionSyncManager } from '@/lib/sync-manager';
 import type { LearnedRuleNotice } from '@/types/automation-rule';
 import type { Transaction } from '@/types/transaction';
@@ -192,7 +192,11 @@ class TransactionSyncService {
         await axios.delete(`/transactions/${id}`, {
             data: options?.updateBalance ? { update_balance: true } : undefined,
         });
-        await db.transactions.delete(id);
+        // The API delete above is authoritative; the local cache eviction is
+        // best-effort and skipped when IndexedDB is unavailable (PHP-LARAVEL-43).
+        await withDb<void>(async () => {
+            await db.transactions.delete(id);
+        }, undefined);
     }
 
     async updateManyIndividual(