@oxyhq/auth 2.0.4 → 2.0.6

package/dist/cjs/WebOxyProvider.js

@@ -40,6 +40,29 @@ function WebOxyProvider({ children, baseURL, authWebUrl, onAuthStateChange, onEr
     const [crossDomainAuth] = (0, react_1.useState)(() => new core_1.CrossDomainAuth(oxyServices));
     const [authManager] = (0, react_1.useState)(() => (0, core_1.createAuthManager)(oxyServices, { autoRefresh: true }));
     const [queryClient] = (0, react_1.useState)(() => (0, queryClient_1.createQueryClient)());
+    // Block first render until the persisted localStorage cache has been
+    // restored — mirrors the RN OxyProvider pattern. Without this gate the
+    // first paint observes an empty cache and any consumer reading
+    // `getQueryData(...)` synchronously (or using `placeholderData: 'previous'`
+    // gating) misses the persisted blob.
+    //
+    // Persistence is attached inside the same effect so we can hold a
+    // reference to the `restored` promise and only flip `isRestoring` to
+    // false once it settles (success OR failure). Detach on unmount so HMR
+    // doesn't leak subscriptions.
+    const [isRestoring, setIsRestoring] = (0, react_1.useState)(true);
+    (0, react_1.useEffect)(() => {
+        let mounted = true;
+        const { restored, unsubscribe } = (0, queryClient_1.attachQueryPersistence)(queryClient);
+        restored.finally(() => {
+            if (mounted)
+                setIsRestoring(false);
+        });
+        return () => {
+            mounted = false;
+            unsubscribe();
+        };
+    }, [queryClient]);
     // Auth state
     const [user, setUser] = (0, react_1.useState)(null);
     const [isLoading, setIsLoading] = (0, react_1.useState)(!skipAutoCheck);
@@ -258,6 +281,20 @@ function WebOxyProvider({ children, baseURL, authWebUrl, onAuthStateChange, onEr
         signIn, signInWithFedCM, signInWithPopup, signInWithRedirect,
         signOut, isFedCMSupported, switchSession, clearSessionState,
     ]);
+    // Mirror the RN OxyProvider pattern: don't expose the QueryClient (or
+    // mount children) until the persisted cache has been restored. On the
+    // web this prevents the first paint from observing an empty
+    // localStorage-backed cache, which would otherwise force every
+    // identity/session/auth query to refetch from the network even when a
+    // fresh blob was available on disk.
+    //
+    // The restored promise is wired with `.finally(...)` upstream, so this
+    // unblocks on both success and failure within typically <50ms (sync
+    // localStorage read + JSON.parse). A safety net is unnecessary: the
+    // restore promise always settles synchronously after one microtask.
+    if (isRestoring) {
+        return null;
+    }
     return ((0, jsx_runtime_1.jsx)(react_query_1.QueryClientProvider, { client: queryClient, children: (0, jsx_runtime_1.jsx)(WebOxyContext.Provider, { value: contextValue, children: children }) }));
 }
 /**

package/dist/cjs/hooks/mutations/index.js

@@ -6,7 +6,7 @@
  * All mutations handle authentication, error handling, and query invalidation.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useRemoveDevice = exports.useUpdateDeviceName = exports.useLogoutAll = exports.useLogoutSession = exports.useSwitchSession = exports.useUploadFile = exports.useUpdatePrivacySettings = exports.useUpdateAccountSettings = exports.useUploadAvatar = exports.useUpdateProfile = void 0;
+exports.useDeleteAppData = exports.useSetAppData = exports.useRemoveDevice = exports.useUpdateDeviceName = exports.useLogoutAll = exports.useLogoutSession = exports.useSwitchSession = exports.useUploadFile = exports.useUpdatePrivacySettings = exports.useUpdateAccountSettings = exports.useUploadAvatar = exports.useUpdateProfile = void 0;
 // Account mutation hooks
 var useAccountMutations_1 = require("./useAccountMutations");
 Object.defineProperty(exports, "useUpdateProfile", { enumerable: true, get: function () { return useAccountMutations_1.useUpdateProfile; } });
@@ -21,3 +21,7 @@ Object.defineProperty(exports, "useLogoutSession", { enumerable: true, get: func
 Object.defineProperty(exports, "useLogoutAll", { enumerable: true, get: function () { return useServicesMutations_1.useLogoutAll; } });
 Object.defineProperty(exports, "useUpdateDeviceName", { enumerable: true, get: function () { return useServicesMutations_1.useUpdateDeviceName; } });
 Object.defineProperty(exports, "useRemoveDevice", { enumerable: true, get: function () { return useServicesMutations_1.useRemoveDevice; } });
+// App-data KV store mutation hooks
+var useAppData_1 = require("./useAppData");
+Object.defineProperty(exports, "useSetAppData", { enumerable: true, get: function () { return useAppData_1.useSetAppData; } });
+Object.defineProperty(exports, "useDeleteAppData", { enumerable: true, get: function () { return useAppData_1.useDeleteAppData; } });

package/dist/cjs/hooks/mutations/useAccountMutations.js

@@ -12,7 +12,7 @@ const authStore_1 = require("../../stores/authStore");
  * Update user profile with optimistic updates and offline queue support
  */
 const useUpdateProfile = () => {
-    const { oxyServices, activeSessionId, user } = (0, WebOxyProvider_1.useWebOxy)();
+    const { oxyServices, activeSessionId } = (0, WebOxyProvider_1.useWebOxy)();
     const queryClient = (0, react_query_1.useQueryClient)();
     return (0, react_query_1.useMutation)({
         mutationFn: async (updates) => {
@@ -40,12 +40,30 @@ const useUpdateProfile = () => {
             }
             return { previousUser };
         },
-        // On error, rollback
+        // On error, rollback ONLY the keys this mutation tried to change
         onError: (error, updates, context) => {
-            if (context?.previousUser) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), context.previousUser);
+            if (context?.previousUser && updates) {
+                const previousUser = context.previousUser;
+                const changedKeys = Object.keys(updates);
+                const partialRollback = changedKeys.reduce((acc, key) => {
+                    acc[key] = previousUser[key];
+                    return acc;
+                }, {});
+                const current = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+                if (current) {
+                    queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), {
+                        ...current,
+                        ...partialRollback,
+                    });
+                }
                 if (activeSessionId) {
-                    queryClient.setQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId), context.previousUser);
+                    const currentProfile = queryClient.getQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId));
+                    if (currentProfile) {
+                        queryClient.setQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId), {
+                            ...currentProfile,
+                            ...partialRollback,
+                        });
+                    }
                 }
             }
             sonner_1.toast.error(error instanceof Error ? error.message : 'Failed to update profile');
@@ -63,9 +81,13 @@ const useUpdateProfile = () => {
             if (updates.avatar && activeSessionId && oxyServices) {
                 (0, avatarUtils_1.refreshAvatarInStore)(activeSessionId, updates.avatar, oxyServices);
             }
-            // Invalidate all related queries to refresh everywhere
+            // Invalidate all related queries so every consumer (AccountSwitcher,
+            // session lists, managed accounts, etc.) refetches the fresh profile.
+            // Critical right after `username` is set the first time, when every
+            // cached "session profile" still reports the user as unnamed.
             (0, queryKeys_1.invalidateUserQueries)(queryClient);
             (0, queryKeys_1.invalidateAccountQueries)(queryClient);
+            (0, queryKeys_1.invalidateSessionQueries)(queryClient);
         },
     });
 };
@@ -106,11 +128,25 @@ const useUploadAvatar = () => {
             }
             return { previousUser };
         },
-        onError: (error, file, context) => {
+        onError: (error, _file, context) => {
+            // Avatar upload only mutates the `avatar` field — restore only that key
             if (context?.previousUser) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), context.previousUser);
+                const previousAvatar = context.previousUser.avatar;
+                const current = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+                if (current) {
+                    queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), {
+                        ...current,
+                        avatar: previousAvatar,
+                    });
+                }
                 if (activeSessionId) {
-                    queryClient.setQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId), context.previousUser);
+                    const currentProfile = queryClient.getQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId));
+                    if (currentProfile) {
+                        queryClient.setQueryData(queryKeys_1.queryKeys.users.profile(activeSessionId), {
+                            ...currentProfile,
+                            avatar: previousAvatar,
+                        });
+                    }
                 }
             }
             sonner_1.toast.error(error instanceof Error ? error.message : 'Failed to upload avatar');
@@ -126,25 +162,47 @@ const useUploadAvatar = () => {
             if (data?.avatar && activeSessionId && oxyServices) {
                 (0, avatarUtils_1.refreshAvatarInStore)(activeSessionId, data.avatar, oxyServices);
             }
-            // Invalidate all related queries to refresh everywhere
+            // Invalidate all related queries to refresh everywhere, including the
+            // sessions cache so other-account avatars update too.
             (0, queryKeys_1.invalidateUserQueries)(queryClient);
             (0, queryKeys_1.invalidateAccountQueries)(queryClient);
+            (0, queryKeys_1.invalidateSessionQueries)(queryClient);
             sonner_1.toast.success('Avatar updated successfully');
         },
     });
 };
 exports.useUploadAvatar = useUploadAvatar;
 /**
- * Update account settings
+ * Update account settings (privacy preferences).
+ *
+ * Privacy settings are not part of the `PUT /users/me` allow-list; the API
+ * would silently drop them. Route through `updatePrivacySettings` so the
+ * dedicated `PATCH /privacy/:id/privacy` endpoint performs a dot-path merge
+ * and returns the updated `privacySettings` object.
+ *
+ * The returned object exposes the standard mutation surface PLUS a
+ * convenience `mutate(updates)` / `mutateAsync(updates)` that snapshots
+ * the current user from `useWebOxy()` at dispatch time.
  */
 const useUpdateAccountSettings = () => {
-    const { oxyServices, activeSessionId } = (0, WebOxyProvider_1.useWebOxy)();
+    const { oxyServices, activeSessionId, user } = (0, WebOxyProvider_1.useWebOxy)();
     const queryClient = (0, react_query_1.useQueryClient)();
-    return (0, react_query_1.useMutation)({
-        mutationFn: async (settings) => {
-            return await oxyServices.updateProfile({ privacySettings: settings });
+    const mutation = (0, react_query_1.useMutation)({
+        mutationFn: async ({ updates, currentUser }) => {
+            const userId = currentUser.id;
+            if (!userId) {
+                throw new Error('User ID is required to update account settings');
+            }
+            const updatedPrivacy = await (0, core_1.authenticatedApiCall)(oxyServices, activeSessionId, () => oxyServices.updatePrivacySettings(updates, userId));
+            // Rebuild against the dispatch-time snapshot, NOT the live cache.
+            // The cache may have been mutated by a sibling write between
+            // dispatch and settle.
+            return {
+                ...currentUser,
+                privacySettings: updatedPrivacy,
+            };
         },
-        onMutate: async (settings) => {
+        onMutate: async ({ updates }) => {
             await queryClient.cancelQueries({ queryKey: queryKeys_1.queryKeys.accounts.settings() });
             const previousUser = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
             if (previousUser) {
@@ -152,15 +210,31 @@ const useUpdateAccountSettings = () => {
                     ...previousUser,
                     privacySettings: {
                         ...previousUser.privacySettings,
-                        ...settings,
+                        ...updates,
                     },
                 });
             }
             return { previousUser };
         },
-        onError: (error, settings, context) => {
-            if (context?.previousUser) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), context.previousUser);
+        onError: (error, { updates }, context) => {
+            // Restore only the privacySettings keys this mutation tried to change
+            if (context?.previousUser && updates) {
+                const previousPrivacy = context.previousUser.privacySettings ?? {};
+                const changedKeys = Object.keys(updates);
+                const partialPrivacyRollback = changedKeys.reduce((acc, key) => {
+                    acc[key] = previousPrivacy[key];
+                    return acc;
+                }, {});
+                const current = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+                if (current) {
+                    queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), {
+                        ...current,
+                        privacySettings: {
+                            ...(current.privacySettings ?? {}),
+                            ...partialPrivacyRollback,
+                        },
+                    });
+                }
             }
             sonner_1.toast.error(error instanceof Error ? error.message : 'Failed to update settings');
         },
@@ -175,6 +249,26 @@ const useUpdateAccountSettings = () => {
             queryClient.invalidateQueries({ queryKey: queryKeys_1.queryKeys.accounts.settings() });
         },
     });
+    // Wrap mutate/mutateAsync so call sites pass a plain settings object and
+    // the current user is captured at dispatch time.
+    return {
+        ...mutation,
+        mutate: (updates) => {
+            const currentUser = user ?? queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+            if (!currentUser) {
+                sonner_1.toast.error('Cannot update account settings: no current user');
+                return;
+            }
+            mutation.mutate({ updates, currentUser });
+        },
+        mutateAsync: async (updates) => {
+            const currentUser = user ?? queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+            if (!currentUser) {
+                throw new Error('Cannot update account settings: no current user');
+            }
+            return mutation.mutateAsync({ updates, currentUser });
+        },
+    };
 };
 exports.useUpdateAccountSettings = useUpdateAccountSettings;
 /**
@@ -221,43 +315,91 @@ const useUpdatePrivacySettings = () => {
             }
             return { previousPrivacySettings, previousUser };
         },
-        // On error, rollback
-        onError: (error, { userId }, context) => {
+        // On error, rollback ONLY the privacy keys this mutation tried to change.
+        // Restoring the entire previous object would wipe out other concurrent
+        // optimistic updates (e.g. user toggles two privacy switches in quick
+        // succession; failure on one must not revert the other).
+        onError: (error, { settings, userId }, context) => {
             const targetUserId = userId || user?.id;
-            if (context?.previousPrivacySettings && targetUserId) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.privacy.settings(targetUserId), context.previousPrivacySettings);
+            const changedKeys = settings ? Object.keys(settings) : [];
+            // Rollback the privacy.settings query (partial)
+            if (context?.previousPrivacySettings && targetUserId && changedKeys.length > 0) {
+                const previousPrivacy = context.previousPrivacySettings;
+                const partialPrivacyRollback = changedKeys.reduce((acc, key) => {
+                    acc[key] = previousPrivacy[key];
+                    return acc;
+                }, {});
+                const currentPrivacy = queryClient.getQueryData(queryKeys_1.queryKeys.privacy.settings(targetUserId));
+                if (currentPrivacy) {
+                    queryClient.setQueryData(queryKeys_1.queryKeys.privacy.settings(targetUserId), {
+                        ...currentPrivacy,
+                        ...partialPrivacyRollback,
+                    });
+                }
             }
-            if (context?.previousUser) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), context.previousUser);
+            // Rollback the accounts.current() user.privacySettings (partial)
+            if (context?.previousUser && changedKeys.length > 0) {
+                const previousPrivacy = (context.previousUser.privacySettings ?? {});
+                const partialPrivacyRollback = changedKeys.reduce((acc, key) => {
+                    acc[key] = previousPrivacy[key];
+                    return acc;
+                }, {});
+                const current = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
+                if (current) {
+                    queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), {
+                        ...current,
+                        privacySettings: {
+                            ...(current.privacySettings ?? {}),
+                            ...partialPrivacyRollback,
+                        },
+                    });
+                }
+            }
+            // After partial rollback, reconcile against the server so the cache
+            // converges to the authoritative state for the failed keys.
+            if (targetUserId) {
+                queryClient.invalidateQueries({ queryKey: queryKeys_1.queryKeys.privacy.settings(targetUserId) });
             }
             sonner_1.toast.error(error instanceof Error ? error.message : 'Failed to update privacy settings');
         },
-        // On success, invalidate and refetch
-        onSuccess: (data, { userId }) => {
+        // On success, MERGE the server response into the cached state. Older
+        // API builds returned only the changed field (or wiped the privacySettings
+        // subdocument when handed a partial update), which would clobber every
+        // other toggle if we blindly replaced. Defensive merge means the UI stays
+        // consistent regardless of server behaviour.
+        //
+        // BOTH the privacy.settings query AND the accounts.current() user are
+        // gated on `targetUserId`. If it's missing (no userId param, no logged-in
+        // user) the optimistic update in onMutate would have early-returned too,
+        // so neither cache was ever touched — there's nothing to reconcile here.
+        onSuccess: (data, { userId, settings }) => {
             const targetUserId = userId || user?.id;
-            if (targetUserId) {
-                queryClient.setQueryData(queryKeys_1.queryKeys.privacy.settings(targetUserId), data);
-            }
-            // Also update account query if it contains privacy settings
+            if (!targetUserId)
+                return;
+            const incoming = (data ?? {});
+            const requested = (settings ?? {});
+            queryClient.setQueryData(queryKeys_1.queryKeys.privacy.settings(targetUserId), (previous) => ({
+                ...(previous ?? {}),
+                ...requested,
+                ...incoming, // server wins for fields it explicitly returned
+            }));
             const currentUser = queryClient.getQueryData(queryKeys_1.queryKeys.accounts.current());
             if (currentUser) {
                 const updatedUser = {
                     ...currentUser,
-                    privacySettings: data,
+                    privacySettings: {
+                        ...(currentUser.privacySettings ?? {}),
+                        ...requested,
+                        ...incoming,
+                    },
                 };
                 queryClient.setQueryData(queryKeys_1.queryKeys.accounts.current(), updatedUser);
-                // Update authStore so frontend components see the changes immediately
                 authStore_1.useAuthStore.getState().setUser(updatedUser);
             }
-            (0, queryKeys_1.invalidateAccountQueries)(queryClient);
-        },
-        // Always refetch after error or success
-        onSettled: (data, error, { userId }) => {
-            const targetUserId = userId || user?.id;
-            if (targetUserId) {
-                queryClient.invalidateQueries({ queryKey: queryKeys_1.queryKeys.privacy.settings(targetUserId) });
-            }
-            queryClient.invalidateQueries({ queryKey: queryKeys_1.queryKeys.accounts.current() });
+            // Deliberately NOT invalidating any queries here. invalidateAccountQueries
+            // invalidates accounts.all which is the prefix for accounts.current(),
+            // triggering a background refetch of useCurrentUser that would overwrite
+            // the merged state above. The onSuccess merge is the source of truth.
         },
     });
 };

package/dist/cjs/hooks/mutations/useAppData.js

@@ -0,0 +1,133 @@
+"use strict";
+/**
+ * App-Data Mutation Hooks
+ *
+ * Write side of the per-user JSON KV store. Both `useSetAppData` and
+ * `useDeleteAppData` apply optimistic updates against the two query keys
+ * that observe this data (`appDataQueryKeys.value` and the surrounding
+ * `appDataQueryKeys.namespace`) and roll back on error.
+ *
+ * When the underlying request fails because the endpoint isn't reachable
+ * (404 / network), the mutation still surfaces the error — write attempts
+ * are user-initiated and the caller may want to retry or fall back to
+ * local persistence. Reads are silent about missing endpoints; writes are
+ * not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useDeleteAppData = exports.useSetAppData = void 0;
+const react_query_1 = require("@tanstack/react-query");
+const core_1 = require("@oxyhq/core");
+const WebOxyProvider_1 = require("../../WebOxyProvider");
+const appDataQueryKeys_1 = require("../queries/appDataQueryKeys");
+/**
+ * Upsert a per-user JSON value. Returns the value the server confirmed it
+ * stored — typically identical to the input but consumers should prefer the
+ * returned value (the server is the source of truth).
+ *
+ * Applies optimistic updates against both the single-value query key and
+ * the surrounding namespace query key, then rolls back on error.
+ */
+const useSetAppData = () => {
+    const { oxyServices, activeSessionId } = (0, WebOxyProvider_1.useWebOxy)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationKey: ['appData', 'set'],
+        mutationFn: async ({ namespace, key, value }) => {
+            return (0, core_1.authenticatedApiCall)(oxyServices, activeSessionId, () => oxyServices.setAppData(namespace, key, value));
+        },
+        onMutate: async ({ namespace, key, value }) => {
+            const valueKey = appDataQueryKeys_1.appDataQueryKeys.value(namespace, key);
+            const namespaceKey = appDataQueryKeys_1.appDataQueryKeys.namespace(namespace);
+            await Promise.all([
+                queryClient.cancelQueries({ queryKey: valueKey }),
+                queryClient.cancelQueries({ queryKey: namespaceKey }),
+            ]);
+            const previousValue = queryClient.getQueryData(valueKey);
+            const previousNamespace = queryClient.getQueryData(namespaceKey);
+            queryClient.setQueryData(valueKey, value);
+            if (previousNamespace) {
+                queryClient.setQueryData(namespaceKey, {
+                    ...previousNamespace,
+                    [key]: value,
+                });
+            }
+            return { previousValue, previousNamespace };
+        },
+        onError: (_error, { namespace, key }, context) => {
+            if (!context)
+                return;
+            const valueKey = appDataQueryKeys_1.appDataQueryKeys.value(namespace, key);
+            const namespaceKey = appDataQueryKeys_1.appDataQueryKeys.namespace(namespace);
+            // Restore exactly the snapshots we captured in onMutate. Don't merge
+            // with whatever's currently in the cache — that could splice in writes
+            // from concurrent mutations and undo their state.
+            queryClient.setQueryData(valueKey, context.previousValue ?? null);
+            if (context.previousNamespace !== undefined) {
+                queryClient.setQueryData(namespaceKey, context.previousNamespace);
+            }
+        },
+        onSuccess: (data, { namespace, key }) => {
+            const valueKey = appDataQueryKeys_1.appDataQueryKeys.value(namespace, key);
+            const namespaceKey = appDataQueryKeys_1.appDataQueryKeys.namespace(namespace);
+            queryClient.setQueryData(valueKey, data);
+            const existingNamespace = queryClient.getQueryData(namespaceKey);
+            if (existingNamespace) {
+                queryClient.setQueryData(namespaceKey, {
+                    ...existingNamespace,
+                    [key]: data,
+                });
+            }
+        },
+    });
+};
+exports.useSetAppData = useSetAppData;
+/**
+ * Delete a per-user JSON value. Optimistically removes the entry from the
+ * single-value cache and from the surrounding namespace map, then rolls back
+ * on error.
+ */
+const useDeleteAppData = () => {
+    const { oxyServices, activeSessionId } = (0, WebOxyProvider_1.useWebOxy)();
+    const queryClient = (0, react_query_1.useQueryClient)();
+    return (0, react_query_1.useMutation)({
+        mutationKey: ['appData', 'delete'],
+        mutationFn: async ({ namespace, key }) => {
+            await (0, core_1.authenticatedApiCall)(oxyServices, activeSessionId, () => oxyServices.deleteAppData(namespace, key));
+        },
+        onMutate: async ({ namespace, key }) => {
+            const valueKey = appDataQueryKeys_1.appDataQueryKeys.value(namespace, key);
+            const namespaceKey = appDataQueryKeys_1.appDataQueryKeys.namespace(namespace);
+            await Promise.all([
+                queryClient.cancelQueries({ queryKey: valueKey }),
+                queryClient.cancelQueries({ queryKey: namespaceKey }),
+            ]);
+            const previousValue = queryClient.getQueryData(valueKey);
+            const previousNamespace = queryClient.getQueryData(namespaceKey);
+            queryClient.setQueryData(valueKey, null);
+            if (previousNamespace && key in previousNamespace) {
+                const next = { ...previousNamespace };
+                delete next[key];
+                queryClient.setQueryData(namespaceKey, next);
+            }
+            return { previousValue, previousNamespace };
+        },
+        onError: (_error, { namespace, key }, context) => {
+            if (!context)
+                return;
+            const valueKey = appDataQueryKeys_1.appDataQueryKeys.value(namespace, key);
+            const namespaceKey = appDataQueryKeys_1.appDataQueryKeys.namespace(namespace);
+            queryClient.setQueryData(valueKey, context.previousValue ?? null);
+            if (context.previousNamespace !== undefined) {
+                queryClient.setQueryData(namespaceKey, context.previousNamespace);
+            }
+        },
+        onSuccess: (_data, { namespace, key }) => {
+            queryClient.setQueryData(appDataQueryKeys_1.appDataQueryKeys.value(namespace, key), null);
+            // Confirm the value is gone from the namespace cache too. If the
+            // optimistic update wasn't applied (e.g. cache was empty), this is a
+            // no-op; if it was, we already removed it in onMutate, so this is also
+            // a no-op. The work happens in onMutate — onSuccess is the commit point.
+        },
+    });
+};
+exports.useDeleteAppData = useDeleteAppData;

package/dist/cjs/hooks/queries/appDataQueryKeys.js

@@ -0,0 +1,46 @@
+"use strict";
+/**
+ * Query keys + error utilities for `useAppData` hooks.
+ *
+ * Lives next to the hook file so consumers can import the keys directly
+ * when they need to imperatively invalidate a value (e.g. after a non-React
+ * write through `oxyServices.setAppData`).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appDataQueryKeys = void 0;
+exports.isMissingAppDataEndpointError = isMissingAppDataEndpointError;
+exports.appDataQueryKeys = {
+    all: ['appData'],
+    namespaces: () => [...exports.appDataQueryKeys.all, 'namespace'],
+    namespace: (namespace) => [...exports.appDataQueryKeys.namespaces(), namespace],
+    values: () => [...exports.appDataQueryKeys.all, 'value'],
+    value: (namespace, key) => [...exports.appDataQueryKeys.values(), namespace, key],
+};
+/**
+ * True when `error` indicates the app-data endpoint isn't reachable — either
+ * because the API deployment doesn't have it yet (404) or there's a network
+ * failure with no response. We treat these as "no value stored" so consumers
+ * fall back to local persistence without surfacing a user-facing error.
+ *
+ * Anything else (401, 403, 500) propagates normally — those are real bugs
+ * the auth or retry pipeline needs to see.
+ */
+function isMissingAppDataEndpointError(error) {
+    if (!error || typeof error !== 'object') {
+        return false;
+    }
+    const candidate = error;
+    const status = candidate.status ?? candidate.statusCode ?? candidate.response?.status;
+    // 404: endpoint not deployed on this API instance yet.
+    if (status === 404)
+        return true;
+    // Network errors: no response received at all. Common during local dev
+    // when the API server is down, or when offline.
+    if (candidate.code === 'NETWORK_ERROR')
+        return true;
+    const message = typeof candidate.message === 'string' ? candidate.message : '';
+    if (message.includes('Network Error') || message.includes('Failed to fetch')) {
+        return true;
+    }
+    return false;
+}

package/dist/cjs/hooks/queries/index.js

@@ -6,7 +6,7 @@
  * All hooks follow the same pattern with optional `enabled` parameter.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.invalidateSessionQueries = exports.invalidateUserQueries = exports.invalidateAccountQueries = exports.queryKeys = exports.useRecentSecurityActivity = exports.useSecurityActivity = exports.useSecurityInfo = exports.useUserDevices = exports.useDeviceSessions = exports.useSession = exports.useSessions = exports.usePrivacySettings = exports.useUsersBySessions = exports.useUserByUsername = exports.useUserById = exports.useCurrentUser = exports.useUserProfiles = exports.useUserProfile = void 0;
+exports.isMissingAppDataEndpointError = exports.appDataQueryKeys = exports.useAppDataNamespace = exports.useAppData = exports.invalidateSessionQueries = exports.invalidateUserQueries = exports.invalidateAccountQueries = exports.queryKeys = exports.useRecentSecurityActivity = exports.useSecurityActivity = exports.useSecurityInfo = exports.useUserDevices = exports.useDeviceSessions = exports.useSession = exports.useSessions = exports.usePrivacySettings = exports.useUsersBySessions = exports.useUserByUsername = exports.useUserById = exports.useCurrentUser = exports.useUserProfiles = exports.useUserProfile = void 0;
 // Account and user query hooks
 var useAccountQueries_1 = require("./useAccountQueries");
 Object.defineProperty(exports, "useUserProfile", { enumerable: true, get: function () { return useAccountQueries_1.useUserProfile; } });
@@ -33,3 +33,10 @@ Object.defineProperty(exports, "queryKeys", { enumerable: true, get: function ()
 Object.defineProperty(exports, "invalidateAccountQueries", { enumerable: true, get: function () { return queryKeys_1.invalidateAccountQueries; } });
 Object.defineProperty(exports, "invalidateUserQueries", { enumerable: true, get: function () { return queryKeys_1.invalidateUserQueries; } });
 Object.defineProperty(exports, "invalidateSessionQueries", { enumerable: true, get: function () { return queryKeys_1.invalidateSessionQueries; } });
+// App-data KV store query hooks
+var useAppData_1 = require("./useAppData");
+Object.defineProperty(exports, "useAppData", { enumerable: true, get: function () { return useAppData_1.useAppData; } });
+Object.defineProperty(exports, "useAppDataNamespace", { enumerable: true, get: function () { return useAppData_1.useAppDataNamespace; } });
+var appDataQueryKeys_1 = require("./appDataQueryKeys");
+Object.defineProperty(exports, "appDataQueryKeys", { enumerable: true, get: function () { return appDataQueryKeys_1.appDataQueryKeys; } });
+Object.defineProperty(exports, "isMissingAppDataEndpointError", { enumerable: true, get: function () { return appDataQueryKeys_1.isMissingAppDataEndpointError; } });