@oxy.so/services 1.0.0

package/src/ui/hooks/queries/__tests__/userCacheClear.test.ts

@@ -0,0 +1,301 @@
+/**
+ * userCache — DELIBERATE CLEARS vs sparse sources.
+ *
+ * `upsertCachedUser` refuses an empty incoming value so a sparse feed/post/list
+ * author can never blank a field the authoritative profile fetch stored. That is
+ * right for a projection and wrong for a user who just removed their picture,
+ * and the payload cannot tell the two apart: oxy-api's `formatUserResponse`
+ * emits a cleared field as `undefined`, which `JSON.stringify` drops, so a
+ * cleared avatar and an uncarried one arrive byte-identical. The caller declares
+ * the difference with `{ cleared: [...] }`.
+ *
+ * WHAT MAKES THIS SUITE NON-VACUOUS
+ * ---------------------------------
+ * Every assertion here is paired: the SAME incoming payload is upserted once
+ * WITHOUT `cleared` and once WITH it, and the two must disagree. A suite whose
+ * fixtures only ever passed `cleared` could not tell "the guard was removed"
+ * from "the clear works", which is the whole risk — dropping the guard would
+ * blank real avatars across every Oxy app. The `does not` half of each pair is
+ * what pins the guard; `userCache.test.ts` keeps its own anti-degradation
+ * coverage independently.
+ */
+
+import { QueryClient } from '@tanstack/react-query';
+import {
+  CLEARABLE_USER_FIELDS,
+  clearedFieldsFromAccountUpdate,
+  clearedFieldsFromProfileUpdate,
+  upsertCachedUser,
+  upsertCachedUsers,
+} from '../userCache';
+import type { CacheableUser, ClearableUserField } from '../userCache';
+import { queryKeys } from '../queryKeys';
+import { useAuthStore } from '../../../stores/authStore';
+
+function makeClient(): QueryClient {
+  return new QueryClient({ defaultOptions: { queries: { retry: false } } });
+}
+
+function readById(qc: QueryClient, id: string): CacheableUser | undefined {
+  return qc.getQueryData<CacheableUser>(queryKeys.users.detail(id));
+}
+
+function readByUsername(
+  qc: QueryClient,
+  username: string,
+  viewerId: string,
+): CacheableUser | undefined {
+  return qc.getQueryData<CacheableUser>(
+    queryKeys.users.byUsername(username, viewerId),
+  );
+}
+
+/** A warm, fully-populated entry — what an authoritative profile fetch stored. */
+function seedFullEntry(qc: QueryClient, viewerId = ''): void {
+  const full = {
+    id: 'u1',
+    username: 'alice',
+    name: { displayName: 'Alice A', first: 'Alice' },
+    avatar: 'file_old',
+    bio: 'old bio',
+    description: 'old description',
+    color: 'teal',
+    accountCategories: ['agency'],
+    _count: { followers: 10, following: 5 },
+  };
+  qc.setQueryData(queryKeys.users.detail('u1'), full);
+  qc.setQueryData(queryKeys.users.byUsername('alice', viewerId), {
+    ...full,
+    relationship: { isFollowing: true, followsYou: true },
+  });
+}
+
+/**
+ * The write response for an account that just emptied everything, in the shape
+ * oxy-api's `formatUserResponse` actually produces — MEASURED, not assumed:
+ *
+ *   {"id":"acc1","publicKey":"pk","username":"chan","name":{},"languages":[]}
+ *
+ * The two details that matter and are easy to get wrong: every cleared scalar is
+ * OMITTED (serialized as `undefined`, which `JSON.stringify` drops), while
+ * `name` survives as a PRESENT-but-EMPTY object. Writing this fixture as
+ * `{ id, username }` instead — with no `name` key — routes `mergeName` down its
+ * "incoming absent" branch and leaves the "incoming present, displayName empty"
+ * branch untested; mutation-testing caught exactly that. Nothing in this object
+ * says "cleared", which is the whole point.
+ */
+const clearedResponse: CacheableUser = { id: 'u1', username: 'alice', name: {} };
+
+/**
+ * The same clear expressed the way a caller echoing its own REQUEST would send
+ * it: `UserProfileUpdate` clears a display name with `''`. It must land on the
+ * same result as the response shape above.
+ */
+const clearedByEmptyString: CacheableUser = {
+  id: 'u1',
+  username: 'alice',
+  name: { displayName: '' },
+};
+
+beforeEach(() => {
+  useAuthStore.setState({ user: null });
+});
+
+describe('upsertCachedUser — a declared clear empties the field', () => {
+  it.each(
+    CLEARABLE_USER_FIELDS.filter(
+      (field): field is Exclude<ClearableUserField, 'name.displayName'> =>
+        field !== 'name.displayName',
+    ),
+  )('drops a stale `%s` only when the caller declares it cleared', (field) => {
+    // WITHOUT the declaration: the guard holds, the stored value survives.
+    const guarded = makeClient();
+    seedFullEntry(guarded);
+    upsertCachedUser(guarded, clearedResponse, '');
+    expect(readById(guarded, 'u1')?.[field]).toBeDefined();
+
+    // WITH it: the same payload now empties exactly that field.
+    const cleared = makeClient();
+    seedFullEntry(cleared);
+    upsertCachedUser(cleared, clearedResponse, '', { cleared: [field] });
+    expect(readById(cleared, 'u1')?.[field]).toBeUndefined();
+  });
+
+  // Three `name` shapes, because `mergeName` branches on them and a single
+  // fixture leaves one branch untested (mutation-verified): the measured
+  // response carries `name: {}`, a request echo carries `name: {displayName:''}`,
+  // and a caller passing a bare object carries no `name` key at all.
+  it.each([
+    ['present but empty (the measured oxy-api shape)', clearedResponse],
+    ['an explicit empty displayName (the request shape)', clearedByEmptyString],
+    ['no `name` key at all', { id: 'u1', username: 'alice' } as CacheableUser],
+  ])(
+    'drops a stale display name only when declared — incoming name %s',
+    (_label, incoming) => {
+      const guarded = makeClient();
+      seedFullEntry(guarded);
+      upsertCachedUser(guarded, incoming, '');
+      expect(readById(guarded, 'u1')?.name).toEqual({
+        displayName: 'Alice A',
+        first: 'Alice',
+      });
+
+      const cleared = makeClient();
+      seedFullEntry(cleared);
+      upsertCachedUser(cleared, incoming, '', {
+        cleared: ['name.displayName'],
+      });
+      // `first` is not what was cleared and must survive — a clear is per-field,
+      // not "drop the whole `name` object".
+      expect(readById(cleared, 'u1')?.name).toEqual({ first: 'Alice' });
+    },
+  );
+
+  it('never lets the "Unknown user" sentinel survive a declared display-name clear', () => {
+    // The ghost-author sentinel is not a real value, so it must not block the
+    // clear either — it is "empty" for this purpose, exactly as it is for the
+    // anti-degradation guard.
+    const qc = makeClient();
+    seedFullEntry(qc);
+    upsertCachedUser(
+      qc,
+      { id: 'u1', username: 'alice', name: { displayName: 'Unknown user' } },
+      '',
+      { cleared: ['name.displayName'] },
+    );
+    expect(readById(qc, 'u1')?.name).toEqual({ first: 'Alice' });
+  });
+
+  it('clears under the by-username key too, not just by-id', () => {
+    const qc = makeClient();
+    seedFullEntry(qc, 'viewer-1');
+    upsertCachedUser(qc, clearedResponse, 'viewer-1', { cleared: ['avatar'] });
+
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.avatar).toBeUndefined();
+    expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+  });
+
+  it('clears ONLY the declared fields, leaving every other one intact', () => {
+    const qc = makeClient();
+    seedFullEntry(qc);
+    upsertCachedUser(qc, clearedResponse, '', { cleared: ['avatar'] });
+
+    const entry = readById(qc, 'u1');
+    expect(entry?.avatar).toBeUndefined();
+    // Vacuity floor: if a clear were implemented as "drop everything absent
+    // from the payload", all of these would be gone too and the test above
+    // would still pass.
+    expect(entry?.bio).toBe('old bio');
+    expect(entry?.description).toBe('old description');
+    expect(entry?.color).toBe('teal');
+    expect(entry?.name).toEqual({ displayName: 'Alice A', first: 'Alice' });
+    expect(entry?._count).toEqual({ followers: 10, following: 5 });
+  });
+
+  it('never drops the viewer relationship, whatever is declared', () => {
+    // `relationship` is not declarable (it is absent from CLEARABLE_USER_FIELDS)
+    // and is server-derived, never user-emptied. Dropping it is the
+    // "Follows you tag vanishes" bug this module exists to prevent.
+    const qc = makeClient();
+    seedFullEntry(qc, 'viewer-1');
+    upsertCachedUser(qc, clearedResponse, 'viewer-1', {
+      cleared: [...CLEARABLE_USER_FIELDS],
+    });
+
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.relationship).toEqual({
+      isFollowing: true,
+      followsYou: true,
+    });
+    expect(readByUsername(qc, 'alice', 'viewer-1')?.username).toBe('alice');
+  });
+});
+
+describe('upsertCachedUser — a declared clear never beats a real value', () => {
+  it('keeps a meaningful incoming value for a field declared cleared', () => {
+    // The server-COMPOSED display name case: clearing the EXPLICIT name makes
+    // oxy-api return the composed one, which must be stored rather than
+    // blanked. Same rule for every field: `cleared` lowers the guard, it does
+    // not force an erasure.
+    const qc = makeClient();
+    seedFullEntry(qc);
+
+    upsertCachedUser(
+      qc,
+      {
+        id: 'u1',
+        username: 'alice',
+        name: { displayName: 'Alice Anderson' },
+        avatar: 'file_new',
+      },
+      '',
+      { cleared: ['name.displayName', 'avatar'] },
+    );
+
+    expect(readById(qc, 'u1')?.name).toEqual({
+      displayName: 'Alice Anderson',
+      first: 'Alice',
+    });
+    expect(readById(qc, 'u1')?.avatar).toBe('file_new');
+  });
+
+  it('treats an explicit null and an empty string as cleared, not as values', () => {
+    // oxy-api omits a cleared field, but `UpdateAccountInput` clears with `null`
+    // and `UserProfileUpdate` clears with `''`, so a caller echoing its own
+    // request must land on the same result as one passing the response.
+    for (const empty of [null, '', '   ']) {
+      const qc = makeClient();
+      seedFullEntry(qc);
+      upsertCachedUser(qc, { id: 'u1', username: 'alice', avatar: empty }, '', {
+        cleared: ['avatar'],
+      });
+      expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+    }
+  });
+
+  it('is a no-op on a cold slot (nothing stale to drop)', () => {
+    const qc = makeClient();
+    upsertCachedUser(qc, clearedResponse, '', { cleared: ['avatar'] });
+
+    expect(readById(qc, 'u1')).toMatchObject({ id: 'u1', username: 'alice' });
+    expect(readById(qc, 'u1')?.avatar).toBeUndefined();
+    // The cold-slot stale-seed contract still holds.
+    expect(qc.getQueryState(queryKeys.users.detail('u1'))?.dataUpdatedAt).toBe(0);
+  });
+});
+
+describe('upsertCachedUsers — the batch path stays guarded', () => {
+  it('takes no clear declaration and never empties a field', () => {
+    // A batch is a multi-user projection: exactly the sparse source the guard
+    // exists for. If it ever grows a `cleared` option this test should fail.
+    const qc = makeClient();
+    seedFullEntry(qc);
+
+    upsertCachedUsers(qc, [{ id: 'u1', username: 'alice', avatar: null }], '');
+
+    expect(readById(qc, 'u1')?.avatar).toBe('file_old');
+  });
+});
+
+describe('clearedFieldsFromProfileUpdate', () => {
+  it('names only fields the patch deliberately emptied', () => {
+    expect(
+      clearedFieldsFromProfileUpdate({ avatar: '', bio: '', name: { displayName: '' } }),
+    ).toEqual(['avatar', 'bio', 'name.displayName']);
+    expect(clearedFieldsFromProfileUpdate({ avatar: 'file_new', bio: 'hello' })).toEqual([]);
+    expect(clearedFieldsFromProfileUpdate({ color: null })).toEqual(['color']);
+  });
+});
+
+describe('clearedFieldsFromAccountUpdate', () => {
+  it('treats null clears on managed accounts like profile clears', () => {
+    expect(
+      clearedFieldsFromAccountUpdate({
+        avatar: null,
+        bio: null,
+        accountCategories: [],
+        name: { displayName: '' },
+      }),
+    ).toEqual(['avatar', 'bio', 'accountCategories', 'name.displayName']);
+    expect(clearedFieldsFromAccountUpdate({ bio: 'still here' })).toEqual([]);
+  });
+});

package/src/ui/hooks/queries/paymentTypes.ts

@@ -0,0 +1,142 @@
+/**
+ * Payment / wallet / subscription domain types.
+ *
+ * These model the JSON shapes the Oxy API actually returns for the
+ * payment-related read endpoints, so the corresponding query hooks
+ * (`useUserSubscription`, `useUserPayments`, `useUserWallet`,
+ * `useUserWalletTransactions`) expose precise types instead of `any`.
+ *
+ * Source of truth (API):
+ *  - Subscription:  GET /subscription/:userId   -> billing-first normalized
+ *                   subscription JSON (Stripe `BillingSubscription` with legacy
+ *                   `Subscription` fallback), or `{ plan: 'basic' }` when none.
+ *  - Payments:      GET /payments/user          -> `Payment[]` (sendSuccess).
+ *  - Wallet:        GET /wallet/:userId         -> `Wallet` (sendSuccess).
+ *  - Transactions:  GET /wallet/transactions/:userId
+ *                   -> `WalletTransactionsResponse` (sendPaginated envelope).
+ *
+ * All `Date` columns are serialized as ISO-8601 strings over the wire.
+ *
+ * Note: `@oxy.so/services` deliberately does NOT re-export these from
+ * `@oxy.so/core`. They live here because they describe the return shape of
+ * the services-layer query hooks; consumers that need core domain types
+ * import those directly from `@oxy.so/core`.
+ */
+
+/** Subscription tier. Mirrors the `plan` enum on the API `Subscription` model. */
+export type SubscriptionPlan = 'basic' | 'pro' | 'business';
+
+/** Lifecycle state of a subscription. */
+export type SubscriptionStatus = 'active' | 'canceled' | 'expired';
+
+/** Feature flags toggled by the active subscription plan. */
+export interface SubscriptionFeatures {
+  analytics: boolean;
+  premiumBadge: boolean;
+  unlimitedFollowing: boolean;
+  higherUploadLimits: boolean;
+  promotedPosts: boolean;
+  businessTools: boolean;
+}
+
+/**
+ * A user's subscription.
+ *
+ * When a user has never subscribed, the API returns the minimal fallback
+ * `{ plan: 'basic' }`; every other field is therefore optional so the type
+ * covers both the persisted document and the fallback.
+ */
+export interface Subscription {
+  plan: SubscriptionPlan;
+  status?: SubscriptionStatus;
+  /** Account this subscription belongs to (absent on the basic fallback). */
+  userId?: string;
+  /** ISO-8601 timestamp the current period started. */
+  startDate?: string;
+  /** ISO-8601 timestamp the current period ends / renews. */
+  endDate?: string;
+  autoRenew?: boolean;
+  paymentMethod?: string;
+  latestInvoice?: string;
+  features?: SubscriptionFeatures;
+  /** ISO-8601 creation timestamp. */
+  createdAt?: string;
+  /** ISO-8601 last-update timestamp. */
+  updatedAt?: string;
+}
+
+/**
+ * A billing / payment history entry, derived from `deposit` and `purchase`
+ * transactions on the API side (`GET /payments/user`).
+ */
+export interface Payment {
+  id: string;
+  userId: string;
+  type: string;
+  amount: number;
+  status: string;
+  description?: string;
+  itemId?: string;
+  itemType?: string;
+  /** ISO-8601 timestamp the payment was created (maps to `createdAt`). */
+  timestamp?: string;
+  /** ISO-8601 timestamp the payment settled, when applicable. */
+  completedAt?: string;
+}
+
+/** FairCoin wallet balance for a user (`GET /wallet/:userId`). */
+export interface Wallet {
+  userId: string;
+  balance: number;
+  /** On-chain withdrawal address, `null` until one is set. */
+  address: string | null;
+}
+
+/** Direction/category of a wallet transaction. */
+export type WalletTransactionType = 'deposit' | 'withdrawal' | 'transfer' | 'purchase';
+
+/** Settlement state of a wallet transaction. */
+export type WalletTransactionStatus = 'pending' | 'completed' | 'failed' | 'cancelled';
+
+/**
+ * A single wallet ledger entry returned by the transaction-history endpoint.
+ *
+ * The populated `userId` / `recipientId` may arrive either as a bare id
+ * string or as a `{ _id, username }` object depending on Mongoose
+ * population, so both shapes are modelled.
+ */
+export interface WalletTransaction {
+  id: string;
+  userId: string | { _id: string; username?: string };
+  type: WalletTransactionType;
+  amount: number;
+  status: WalletTransactionStatus;
+  description?: string;
+  recipientId?: string | { _id: string; username?: string } | null;
+  itemId?: string;
+  itemType?: string;
+  /** ISO-8601 creation timestamp (maps to `createdAt`). */
+  timestamp?: string;
+  /** ISO-8601 settlement timestamp, when applicable. */
+  completedAt?: string;
+}
+
+/** Pagination metadata attached to a paginated list response. */
+export interface WalletPagination {
+  total: number;
+  limit: number;
+  offset: number;
+  hasMore: boolean;
+}
+
+/**
+ * Paginated envelope returned by `GET /wallet/transactions/:userId`.
+ *
+ * The HTTP layer preserves the `{ data, pagination }` shape for paginated
+ * responses (it only unwraps the plain `{ data }` success envelope), so
+ * callers receive the list under `data`.
+ */
+export interface WalletTransactionsResponse {
+  data: WalletTransaction[];
+  pagination: WalletPagination;
+}

package/src/ui/hooks/queries/queryKeys.ts

@@ -0,0 +1,221 @@
+/**
+ * Centralized query keys for TanStack Query
+ *
+ * Following best practices:
+ * - Use arrays for hierarchical keys
+ * - Include all parameters in the key
+ * - Use consistent naming conventions
+ */
+
+import type { QueryClient } from '@tanstack/react-query';
+
+export const queryKeys = {
+  // Account queries
+  accounts: {
+    all: ['accounts'] as const,
+    lists: () => [...queryKeys.accounts.all, 'list'] as const,
+    list: (sessionIds: string[]) => [...queryKeys.accounts.lists(), sessionIds] as const,
+    details: () => [...queryKeys.accounts.all, 'detail'] as const,
+    detail: (sessionId: string) => [...queryKeys.accounts.details(), sessionId] as const,
+    current: (sessionId?: string | null) =>
+      sessionId
+        ? ([...queryKeys.accounts.all, 'current', sessionId] as const)
+        : ([...queryKeys.accounts.all, 'current'] as const),
+    settings: () => [...queryKeys.accounts.all, 'settings'] as const,
+  },
+
+  // User queries
+  users: {
+    all: ['users'] as const,
+    lists: () => [...queryKeys.users.all, 'list'] as const,
+    list: (userIds: string[]) => [...queryKeys.users.lists(), userIds] as const,
+    details: () => [...queryKeys.users.all, 'detail'] as const,
+    detail: (userId: string) => [...queryKeys.users.details(), userId] as const,
+    /** Viewer-scoped single-profile fetch by user id (`relationship` is viewer-relative). */
+    detailForViewer: (userId: string, viewerId: string) =>
+      [...queryKeys.users.details(), userId, 'viewer', viewerId] as const,
+    /**
+     * Viewer-scoped single-profile fetch by username (`relationship` is
+     * viewer-relative). Username is normalized to `trim().toLowerCase()` here
+     * so the hook key and any external seeder (e.g. Mention's precache) agree
+     * by construction — normalize once, never at call sites.
+     */
+    byUsername: (username: string, viewerId: string) =>
+      [
+        ...queryKeys.users.details(),
+        'username',
+        username.trim().toLowerCase(),
+        'viewer',
+        viewerId,
+      ] as const,
+    profile: (sessionId: string) => [...queryKeys.users.details(), sessionId, 'profile'] as const,
+  },
+
+  // Session queries
+  sessions: {
+    all: ['sessions'] as const,
+    lists: () => [...queryKeys.sessions.all, 'list'] as const,
+    list: (userId?: string) => [...queryKeys.sessions.lists(), userId] as const,
+    details: () => [...queryKeys.sessions.all, 'detail'] as const,
+    detail: (sessionId: string) => [...queryKeys.sessions.details(), sessionId] as const,
+    active: () => [...queryKeys.sessions.all, 'active'] as const,
+    device: (deviceId: string) => [...queryKeys.sessions.all, 'device', deviceId] as const,
+  },
+
+  // Device queries
+  devices: {
+    all: ['devices'] as const,
+    lists: () => [...queryKeys.devices.all, 'list'] as const,
+    list: (accountScope?: string) => [...queryKeys.devices.lists(), accountScope] as const,
+    details: () => [...queryKeys.devices.all, 'detail'] as const,
+    detail: (deviceId: string) => [...queryKeys.devices.details(), deviceId] as const,
+  },
+
+  // Privacy settings queries
+  privacy: {
+    all: ['privacy'] as const,
+    settings: (userId?: string) => [...queryKeys.privacy.all, 'settings', userId || 'current'] as const,
+  },
+
+  // Security activity queries
+  security: {
+    all: ['security'] as const,
+    activity: (limit?: number, offset?: number, eventType?: string) =>
+      [...queryKeys.security.all, 'activity', limit, offset, eventType] as const,
+    recent: (limit: number) =>
+      [...queryKeys.security.all, 'recent', limit] as const,
+    infinite: (limit: number, eventType?: string) =>
+      [...queryKeys.security.all, 'infinite', limit, eventType] as const,
+  },
+
+  // Linked authentication methods (passwords, identity keys, passkeys, social)
+  authMethods: {
+    all: ['authMethods'] as const,
+    list: (userId?: string) => [...queryKeys.authMethods.all, 'list', userId || 'current'] as const,
+  },
+
+  // Storage usage queries
+  storage: {
+    all: ['storage'] as const,
+    usage: (accountScope?: string) => [...queryKeys.storage.all, 'usage', accountScope] as const,
+  },
+
+  // User file library (infinite-paginated; owner-scoped so switching the active
+  // account shows that account's files without a manual reset)
+  files: {
+    all: ['files'] as const,
+    list: (ownerId?: string) => [...queryKeys.files.all, 'list', ownerId || 'anonymous'] as const,
+  },
+
+  // Connected apps (OAuth grants the user has authorized)
+  connectedApps: {
+    all: ['connectedApps'] as const,
+    list: () => [...queryKeys.connectedApps.all, 'list'] as const,
+  },
+
+  // Follow / social graph queries
+  follow: {
+    all: ['follow'] as const,
+    counts: (userId: string) => [...queryKeys.follow.all, 'counts', userId] as const,
+  },
+
+  // Payment / wallet / subscription queries
+  payments: {
+    all: ['payments'] as const,
+    subscription: (userId?: string) =>
+      [...queryKeys.payments.all, 'subscription', userId || 'current'] as const,
+    history: (userId?: string) =>
+      [...queryKeys.payments.all, 'history', userId || 'current'] as const,
+    wallet: (userId?: string) =>
+      [...queryKeys.payments.all, 'wallet', userId || 'current'] as const,
+    walletTransactions: (limit?: number, offset?: number, userId?: string) =>
+      [
+        ...queryKeys.payments.all,
+        'wallet',
+        userId || 'current',
+        'transactions',
+        limit,
+        offset,
+      ] as const,
+  },
+} as const;
+
+/**
+ * Helper to invalidate all account-related queries
+ */
+export const invalidateAccountQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.accounts.all });
+};
+
+/**
+ * Helper to invalidate all user-related queries
+ */
+export const invalidateUserQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.users.all });
+};
+
+/**
+ * Helper to invalidate all session-related queries
+ */
+export const invalidateSessionQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.sessions.all });
+};
+
+/**
+ * Helper to invalidate all device-related queries
+ */
+export const invalidateDeviceQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.devices.all });
+};
+
+/**
+ * Helper to invalidate all privacy-settings queries
+ */
+export const invalidatePrivacyQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.privacy.all });
+};
+
+/**
+ * Helper to invalidate all security-activity queries
+ */
+export const invalidateSecurityQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.security.all });
+};
+
+/**
+ * Helper to invalidate all storage-usage queries
+ */
+export const invalidateStorageQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.storage.all });
+};
+
+/**
+ * Helper to invalidate the user's linked auth-methods list (call after linking
+ * or removing a passkey / password / identity key).
+ */
+export const invalidateAuthMethodsQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.authMethods.all });
+};
+
+/**
+ * Helper to invalidate all payments / wallet / subscription queries
+ */
+export const invalidatePaymentsQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.payments.all });
+};
+
+/**
+ * Helper to invalidate the user's connected-apps list
+ */
+export const invalidateConnectedAppsQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.connectedApps.all });
+};
+
+/**
+ * Helper to invalidate the user's file library (all owners). Pass an ownerId via
+ * `queryKeys.files.list(ownerId)` for a scoped invalidation instead.
+ */
+export const invalidateFileQueries = (queryClient: QueryClient): void => {
+  queryClient.invalidateQueries({ queryKey: queryKeys.files.all });
+};
+