@oxyhq/core 18.0.0 → 19.1.0

package/src/mixins/OxyServices.accounts.ts

@@ -33,10 +33,12 @@
  * registers the switched session into the operator's device-set directly).
  */
 import type { User } from '../models/interfaces';
-import type { AccountKind, OrganizationCategory, ChildAccountKind } from '@oxyhq/contracts';
+import type { AccountCategoryId, AccountKind, ChildAccountKind } from '@oxyhq/contracts';
 import type { SessionLoginResponse } from '../models/session';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { normalizeUserIdentity } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
+import { evictOxyAccountForestCache, oxyAccountDetailCacheKey, OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX } from '../utils/accountCacheSweep';
 import { CACHE_TIMES } from './mixinHelpers';
 
 // ---------------------------------------------------------------------------
@@ -52,8 +54,16 @@ import { CACHE_TIMES } from './mixinHelpers';
  *
  * Single source of truth is `@oxyhq/contracts`.
  */
-export type { AccountKind, OrganizationCategory } from '@oxyhq/contracts';
-export { ACCOUNT_KINDS, ORGANIZATION_CATEGORIES, isActAsEligibleKind } from '@oxyhq/contracts';
+export type { AccountCategoryId, AccountKind } from '@oxyhq/contracts';
+export {
+  ACCOUNT_CATEGORY_IDS,
+  ACCOUNT_KINDS,
+  MAX_ACCOUNT_CATEGORIES,
+  SELECTABLE_ACCOUNT_CATEGORY_IDS,
+  isActAsEligibleKind,
+  isSelectableAccountCategoryId,
+  kindAcceptsAccountCategories,
+} from '@oxyhq/contracts';
 
 /**
  * The calling user's relationship to an account node, as resolved by the API:
@@ -78,8 +88,8 @@ export type AccountMemberStatus = 'active' | 'invited' | 'removed';
 export type AccountMemberSource = 'direct' | 'inherited';
 
 /**
- * Client-facing AccountMember shape. `permissions` is derived from `role` on the
- * server at write time.
+ * Client-facing AccountMember shape. `permissions` is the effective permission
+ * set (role baseline plus `permissionGrants` minus `permissionRevokes`).
  */
 export interface AccountMember {
   _id: string;
@@ -89,6 +99,10 @@ export interface AccountMember {
   memberUserId: string;
   role: AccountRole;
   permissions: string[];
+  /** Permissions granted beyond the role baseline. */
+  permissionGrants?: string[];
+  /** Permissions revoked from the role baseline. */
+  permissionRevokes?: string[];
   /**
    * Whether this membership cascades to the account's subtree. `true` (default)
    * lets descendants inherit this role unless a nearer row overrides it; `false`
@@ -97,12 +111,20 @@ export interface AccountMember {
   inherit: boolean;
   status: AccountMemberStatus;
   /**
-   * Origin of the membership when the API resolves an effective role. Present on
-   * a resolved `callerMembership` to indicate whether the caller's access is
-   * `direct` on the account or `inherited` from an ancestor. Absent on plain
-   * member-list rows (which are always direct rows on the account).
+   * Where this membership COMES FROM relative to the account it is being
+   * reported for: `direct` when the row lives on that account, `inherited` when
+   * it lives on an ancestor whose `inherit` flag cascades it down.
+   *
+   * Present on every membership the API serialises — a resolved
+   * `callerMembership` and every entry of a member list alike. It is not
+   * decoration: an `inherited` entry's `accountId` is the ANCESTOR's, and the
+   * member-mutation endpoints are scoped to rows on the account named in the
+   * path, so `PATCH`/`DELETE .../members/<that row's _id>` against the
+   * descendant 404s. **Branch on `source === 'direct'` before offering to edit,
+   * remove or transfer to a member**, and count owners for a last-owner check
+   * over direct entries only.
    */
-  source?: AccountMemberSource;
+  source: AccountMemberSource;
   invitedByUserId?: string | null;
   joinedAt?: string | null;
   createdAt: string;
@@ -179,8 +201,17 @@ export interface CreateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string;
   avatar?: string;
-  /** Meaningful only when `kind` is `organization`. */
-  organizationCategory?: OrganizationCategory;
+  /**
+   * What the account is about. ORDERED — the FIRST element is the primary
+   * category, so a picker must submit them in the order the user arranged them
+   * and must not sort. Stable ids, never labels: render each one through the
+   * `accounts.accountCategory.<id>` translation key.
+   *
+   * Offer `SELECTABLE_ACCOUNT_CATEGORY_IDS`, not `ACCOUNT_CATEGORY_IDS` — the
+   * latter still contains withdrawn ids so that accounts already carrying one
+   * keep working. At most `MAX_ACCOUNT_CATEGORIES`, no duplicates.
+   */
+  accountCategories?: AccountCategoryId[];
 }
 
 /** Input accepted by `updateAccount`. Tree placement changes go through `/move`. */
@@ -195,8 +226,19 @@ export interface UpdateAccountInput {
   name?: { first?: string; last?: string; displayName?: string };
   bio?: string | null;
   avatar?: string | null;
-  /** Clears the category when `null`; only valid on `kind: 'organization'`. */
-  organizationCategory?: OrganizationCategory | null;
+  /**
+   * Replaces the WHOLE list, in the order given — there is no add/remove verb,
+   * because a partial edit cannot express a re-ordering and the order is what
+   * names the primary category. `[]` clears it.
+   *
+   * Not nullable, unlike `bio` and `avatar`: the empty case already has a
+   * spelling of its own, so a second one could only ever disagree with it.
+   *
+   * Rejected for a `personal` account, and rejected when it ADDS a withdrawn
+   * id the account did not already carry — keeping or re-ordering one it has is
+   * always allowed.
+   */
+  accountCategories?: AccountCategoryId[];
 }
 
 /** Input accepted by `provisionChannelAccount` (service token + `accounts:provision`). */
@@ -235,7 +277,10 @@ export interface InviteAccountMemberInput {
 
 /** Input accepted by `updateAccountMember`. The owner role cannot be assigned. */
 export interface UpdateAccountMemberInput {
-  role: Exclude<AccountRole, 'owner'>;
+  role?: Exclude<AccountRole, 'owner'>;
+  inherit?: boolean;
+  permissionGrants?: string[];
+  permissionRevokes?: string[];
 }
 
 /** Input accepted by `transferAccountOwnership`. */
@@ -673,7 +718,7 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
         );
         // A new account changes the accessible forest — bust every cached list
         // (flat + tree) so it appears on the next `listAccounts()` read.
-        this._invalidateAccountLists();
+        evictOxyAccountForestCache(this);
         return res.account;
       } catch (error) {
         throw this.handleError(error);
@@ -736,6 +781,18 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
     /**
      * Update an account's mutable profile fields. Tree placement changes
      * (reparenting) go through the dedicated move endpoint, not here.
+     *
+     * An account IS a user, so this write changes identity — and a profile
+     * screen never reads `/accounts/<id>`. It reads `GET /users/<id>` and
+     * `GET /profiles/username/<handle>`, both cached for 5 minutes in the
+     * CALLER'S OWN process, so busting only the account-graph keys left every
+     * profile surface serving the pre-edit avatar and name for the full TTL
+     * with a perfectly healthy server (the cross-service `oxy:user:invalidate`
+     * signal does not help: it evicts BACKEND caches, and cannot reach a cache
+     * living in a browser tab). {@link evictOxyIdentityCache} owns that key
+     * list — see its docs for why the handle-keyed entries are prefix-swept
+     * (a RENAME leaves the old handle's entry unreachable by any targeted key).
+     *
      * @param accountId - The account's Mongo `_id`.
      * @param data - Subset of updatable profile fields.
      */
@@ -752,8 +809,17 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
         );
         // Bust the cached detail and every list (which embeds account profile
         // data) so neither serves the pre-update snapshot.
-        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
-        this._invalidateAccountLists();
+        evictOxyAccountForestCache(this, accountId);
+        // The parent's children list embeds this account's profile and is keyed
+        // by the PARENT id, so it is reachable only from the response node.
+        const parentAccountId = res.account?.parentAccountId;
+        if (parentAccountId) {
+          this.clearCacheEntry(
+            `GET:/accounts/${encodeURIComponent(parentAccountId)}/children`,
+          );
+        }
+        // Every identity read of this account, whichever key it lands under.
+        evictOxyIdentityCache(this, accountId);
         return res.account;
       } catch (error) {
         throw this.handleError(error);
@@ -775,10 +841,9 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
           { cache: false },
         );
         // Bust every cached representation of the archived account.
-        this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
         this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
         this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/credentials`);
-        this._invalidateAccountLists();
+        evictOxyAccountForestCache(this, accountId);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -808,7 +873,27 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
     // =========================================================================
 
     /**
-     * List members of an account (direct membership rows on the account).
+     * List the members of an account: the membership rows ON it, plus the rows
+     * on its ancestors that cascade into it. Each entry carries `source`
+     * (`direct` | `inherited`) saying which it is.
+     *
+     * Inherited entries are members in every sense the server enforces — an
+     * ancestor row with `inherit: true` resolves through
+     * `resolveEffectiveAccess` and confers every account permission on the
+     * descendant, `account:act_as` included — so a roster that omitted them
+     * answered `[]` for accounts several people could act on.
+     *
+     * Two things follow for a caller. An entry's `accountId` is the account its
+     * ROW lives on, so an inherited entry names an ancestor rather than the
+     * account you asked about; and the member-mutation endpoints only accept
+     * rows on the account in the path, so gate any edit/remove/transfer
+     * affordance on `source === 'direct'`.
+     *
+     * Asking what the CALLER holds over an account is a different question, and
+     * scanning this list for yourself is the wrong way to answer it — use
+     * {@link OxyServicesAccountsMixin.getAccount}, whose `callerMembership` is
+     * the server's own resolution.
+     *
      * @param accountId - The account's Mongo `_id`.
      */
     async listAccountMembers(accountId: string): Promise<AccountMember[]> {
@@ -917,7 +1002,7 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
         // Ownership change alters roles in the member list AND the detail, and
         // can change which accounts the caller "owns" in the list view.
         this._invalidateAccountMembership(accountId);
-        this._invalidateAccountLists();
+        evictOxyAccountForestCache(this);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -1259,36 +1344,29 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
     // =========================================================================
 
     /**
-     * Bust every cached account list. `listAccounts({tree?})` keys the flat list
-     * as `GET:/accounts` and the tree variant as `GET:/accounts?tree=true` (the
-     * query string is part of the URL path). A change to the accessible forest
-     * (create/archive/ownership transfer) invalidates both, so we clear the
-     * unscoped entry plus every `?`-query variant via a prefix sweep. The prefix
-     * `GET:/accounts?` matches only the query-string list variants, never the
-     * `GET:/accounts/<id>…` detail/sub-resource keys.
+     * Bust the cached member list and detail for an account after a membership
+     * mutation. The member list (`listAccountMembers`) and the detail
+     * (`getAccount`, which can embed the caller's membership) both go stale when
+     * the member set or a member's role changes.
      *
      * Internal helper (leading underscore); not part of the supported public
      * surface. Public rather than `private` because mixins compose into an
      * exported anonymous class, where TypeScript cannot represent a private
      * member in the emitted declaration file (TS4094).
-     */
-    _invalidateAccountLists(): void {
-      this.clearCacheEntry('GET:/accounts');
-      this.clearCacheByPrefix('GET:/accounts?');
-    }
-
-    /**
-     * Bust the cached member list and detail for an account after a membership
-     * mutation. The member list (`listAccountMembers`) and the detail
-     * (`getAccount`, which can embed the caller's membership) both go stale when
-     * the member set or a member's role changes.
      *
-     * Internal helper (leading underscore); see `_invalidateAccountLists` for why
-     * this is public rather than `private`.
+     * The forest keys themselves are NOT owned here — see
+     * `utils/accountCacheSweep`, which the user mixin has to reach as well.
      */
     _invalidateAccountMembership(accountId: string): void {
       this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}/members`);
-      this.clearCacheEntry(`GET:/accounts/${encodeURIComponent(accountId)}`);
+      this.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+      // Inherited rows on descendant rosters are derived from this account's
+      // membership table — a targeted clear of only the mutated account's keys
+      // leaves every other cached `…/members` list serving stale inherited
+      // roles until MEDIUM TTL. Sweep all per-account sub-resource keys instead;
+      // the forest list keys (`GET:/accounts`, `GET:/accounts?…`) are excluded
+      // by the trailing slash on the prefix (see accountCacheSweep).
+      this.clearCacheByPrefix(OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX);
     }
 
     /**
@@ -1300,8 +1378,8 @@ export function OxyServicesAccountsMixin<T extends typeof OxyServicesBase>(Base:
      * query-string list variants, never the `GET:/applications/<id>…`
      * detail/sub-resource keys.
      *
-     * Internal helper (leading underscore); see `_invalidateAccountLists` for why
-     * this is public rather than `private`.
+     * Internal helper (leading underscore); see `_invalidateAccountMembership`
+     * for why this is public rather than `private`.
      */
     _invalidateAppLists(): void {
       this.clearCacheEntry('GET:/applications');

package/src/mixins/OxyServices.followGraph.ts

@@ -0,0 +1,266 @@
+/**
+ * Follow Graph Mixin (`/v2/follows`)
+ *
+ * The user-owned follow graph: one relationship per user and target, shared by
+ * every application, with per-application context on top. This is the SDK half
+ * of #809 and the replacement for the per-app follow endpoints each application
+ * grew for itself.
+ *
+ * ## Why this is not `followUser` with more parameters
+ *
+ * `followUser` answers "does A follow B" and nothing else. This answers "what
+ * does this user follow, anywhere, and which applications act on it" — a
+ * different question with a different owner. The legacy methods stay for the
+ * Mongo-backed social graph they were written for; new kinds (topics, stores,
+ * artists, channels) come here, and users will migrate behind an adapter rather
+ * than through a flag day.
+ *
+ * ## Caching
+ *
+ * Every method is `cache: false`. A follow status is exactly the shape that
+ * must never be served stale: the SDK's GET cache is identity-scoped but
+ * time-based, and a status cached across a write is the "follow reverts after
+ * navigating away and back" bug — which the legacy `followUser` had to fix with
+ * explicit invalidation. Not caching at this layer means an app's own store
+ * (React Query, Zustand) is the single cache authority, which is the rule the
+ * ecosystem already follows for anything written and read in the same session.
+ */
+
+import type {
+  FollowListPage,
+  FollowMutation,
+  FollowOptions,
+  FollowStatus,
+  UnfollowMutation,
+} from '@oxyhq/contracts';
+import type { OxyServicesBase } from '../OxyServices.base';
+import { buildUrl } from '../utils/apiUtils';
+
+export function OxyServicesFollowGraphMixin<T extends typeof OxyServicesBase>(Base: T) {
+  return class extends Base {
+    constructor(...args: any[]) {
+      super(...(args as [any]));
+    }
+
+    /**
+     * Follow a target. Idempotent — following something already followed
+     * returns the same relationship with `created: false`.
+     *
+     * The follower and the acting application are BOTH derived server-side from
+     * the session. There is deliberately no parameter for either: a client that
+     * could name them could forge a follow on another user's behalf, or record
+     * one as coming from an application it is not.
+     *
+     * @param targetId - The registered target's id, not its URI. Registration is
+     *   a separate operation precisely so following cannot silently create
+     *   targets — a typo would otherwise become a permanent row nobody follows.
+     * @param options.expiresIn - Seconds until the follow lapses on its own. For
+     *   an event, a trial, a topic followed for a week. The server bounds it.
+     */
+    async followTarget(targetId: string, options?: FollowOptions): Promise<FollowMutation> {
+      try {
+        return await this.makeRequest<FollowMutation>(
+          'PUT',
+          `/v2/follows/${encodeURIComponent(targetId)}`,
+          options?.expiresIn !== undefined ? { expiresIn: options.expiresIn } : {},
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Unfollow everywhere.
+     *
+     * There is no "unfollow here" — that is `setFollowApplicationMode(...,
+     * 'disabled')`, and keeping the two distinct is the point of the design. An
+     * application that quietly turned a global unfollow into a local one would
+     * leave the user believing they had stopped following something they still
+     * follow everywhere else.
+     *
+     * Idempotent: `removed: false` when it was already gone, because the state
+     * the caller asked for is the state that holds.
+     */
+    async unfollowTarget(relationshipId: string): Promise<UnfollowMutation> {
+      try {
+        return await this.makeRequest<UnfollowMutation>(
+          'DELETE',
+          `/v2/follows/${encodeURIComponent(relationshipId)}`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * The three-part status: globally, in this application, and in effect.
+     *
+     * Render `effectiveState` on the button and keep the other two for the
+     * explanation. A UI that collapses them cannot tell the user why a follow
+     * they can see in their list is not showing up in this app's feed.
+     */
+    async getFollowTargetStatus(targetId: string): Promise<FollowStatus> {
+      try {
+        return await this.makeRequest<FollowStatus>(
+          'GET',
+          `/v2/follows/${encodeURIComponent(targetId)}/status`,
+          undefined,
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Turn a relationship off, or back on, in ONE application.
+     *
+     * Omit `applicationId` and it applies to the calling application, which is
+     * the only form an ordinary app should ever need. Naming a DIFFERENT
+     * application requires `follows:manage` server-side — acting on another
+     * app's behalf is exactly the cross-application authority this design
+     * otherwise refuses, so it is a distinct permission and not a parameter an
+     * app happens to fill in.
+     */
+    async setFollowApplicationMode(
+      relationshipId: string,
+      mode: 'enabled' | 'disabled',
+      applicationId?: string,
+    ): Promise<{ ok: true; mode: 'enabled' | 'disabled' }> {
+      try {
+        return await this.makeRequest(
+          'PUT',
+          `/v2/follows/${encodeURIComponent(relationshipId)}/context`,
+          { mode, ...(applicationId ? { applicationId } : {}) },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Drop the override so this application follows the global relationship
+     * again. Distinct from setting `enabled`: inheriting means a later global
+     * change takes effect here, and an explicit `enabled` means it does not.
+     */
+    async restoreFollowInheritance(
+      relationshipId: string,
+      applicationId?: string,
+    ): Promise<{ ok: true }> {
+      try {
+        const path = buildUrl(
+          `/v2/follows/${encodeURIComponent(relationshipId)}/context`,
+          applicationId ? { applicationId } : {},
+        );
+        return await this.makeRequest('DELETE', path, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Resolve a target by canonical URI, registering it the first time anyone
+     * asks. The call an application makes on the way into a screen, before it
+     * can render a button.
+     *
+     * Idempotent on the URI, which is what makes two applications describing
+     * the same thing — the same fediverse actor, the same topic — arrive at ONE
+     * row, and therefore at one relationship per user rather than one per app.
+     *
+     * `metadata` is a display snapshot (name, handle, icon) and is refreshed
+     * only for the application that provides the target: a second application
+     * passing its own idea of the name would make the display flip depending on
+     * which app last looked.
+     */
+    async ensureFollowTarget(input: {
+      uri: string;
+      kind: string;
+      metadata?: Record<string, unknown>;
+      providerReference?: string;
+      localUserId?: string;
+    }): Promise<{ id: string; uri: string; kind: string; created: boolean }> {
+      try {
+        return await this.makeRequest('POST', '/v2/follow-targets', input, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Claim a namespace for the calling application. First come, and idempotent
+     * for the holder — an application that registers on every boot must not
+     * fail the second time.
+     */
+    async claimFollowNamespace(
+      namespace: string
+    ): Promise<{ namespace: string; created: boolean }> {
+      try {
+        return await this.makeRequest(
+          'POST',
+          '/v2/follow-targets/namespaces',
+          { namespace },
+          { cache: false },
+        );
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Declare what following a kind of thing MEANS: the verb clients render,
+     * whether reverse lookups are public, whether it federates.
+     *
+     * Declared once by the application that owns the concept, rather than
+     * passed per call site — otherwise two screens of one app can disagree
+     * about whether a store is followed or subscribed to.
+     */
+    async registerFollowKind(input: {
+      kind: string;
+      label?: string;
+      capabilities?: {
+        verb?: 'follow' | 'subscribe' | 'join';
+        reverse?: 'public' | 'private' | 'aggregate' | 'unavailable';
+        federated?: boolean;
+      };
+    }): Promise<{ kind: string; created: boolean }> {
+      try {
+        return await this.makeRequest('POST', '/v2/follow-targets/kinds', input, {
+          cache: false,
+        });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Everything the signed-in user follows, newest first.
+     *
+     * Owner-only by construction server-side — there is no parameter naming a
+     * user, so this cannot be pointed at somebody else's graph.
+     *
+     * Paginate by passing back `nextCursor`, never an offset: the list changes
+     * while it is being read, and an offset silently skips or repeats rows
+     * exactly when it does.
+     */
+    async listFollows(params?: {
+      kind?: string;
+      cursor?: string;
+      limit?: number;
+    }): Promise<FollowListPage> {
+      try {
+        const path = buildUrl('/v2/me/follows', {
+          ...(params?.kind ? { kind: params.kind } : {}),
+          ...(params?.cursor ? { cursor: params.cursor } : {}),
+          ...(params?.limit ? { limit: params.limit } : {}),
+        });
+        return await this.makeRequest<FollowListPage>('GET', path, undefined, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+  };
+}

package/src/mixins/OxyServices.user.ts

@@ -28,6 +28,8 @@ import {
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep';
+import { evictOxyAccountForestCache } from '../utils/accountCacheSweep';
 import { logger } from '../logger';
 import { extractErrorStatus } from '../utils/errorUtils';
 
@@ -534,13 +536,16 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     /**
      * Update user profile.
      *
-     * Invalidates the SDK-side response cache for every endpoint that
-     * returns the current user (`GET /users/me`, `GET /session/user/*`,
-     * `GET /users/<id>`, `GET /profiles/username/*`) so the next read
-     * doesn't return a stale snapshot. Without this, a follow-up
-     * `getUserBySession` call inside the 2-minute cache window can return
-     * the pre-update user — most visibly during onboarding, where it
-     * causes the username step to flicker back as if nothing was saved.
+     * Invalidates the SDK-side response cache for every endpoint that can
+     * return this user — the list is owned by {@link evictOxyIdentityCache}, so
+     * a new identity read is added in one place instead of to each writer
+     * separately (this method's own hand-written copy had already drifted from
+     * the server-side one, missing `GET /auth/lookup/*` and
+     * `GET /profiles/resolve`). The account forest (`GET /accounts` and the
+     * caller's own detail row) is swept too — a personal account IS this user,
+     * and `AccountNode.account` embeds the whole profile — from the list that
+     * {@link evictOxyAccountForestCache} owns, for the same reason: the accounts
+     * mixin writes those keys as well, and two hand-written copies drift.
      *
      * TanStack Query handles offline queuing automatically.
      */
@@ -550,15 +555,8 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
           await this.makeRequest<User>('PUT', '/users/me', updates, { cache: false }),
         );
 
-        // Bust every cached representation of the current user. We use a
-        // prefix sweep rather than an enumeration because the SDK never
-        // tracks the set of active session IDs centrally.
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        if (result?.id) {
-          this.clearCacheEntry(`GET:/users/${result.id}`);
-        }
+        evictOxyIdentityCache(this, result?.id);
+        evictOxyAccountForestCache(this, result?.id);
 
         return result;
       } catch (error) {
@@ -615,10 +613,9 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         const result = await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
-        this.clearCacheByPrefix('GET:/session/user/');
-        this.clearCacheByPrefix('GET:/users/me');
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheEntry(`GET:/users/${id}`);
+        // Privacy settings ride the user DTO, so every identity read goes stale
+        // too — same key list as any other profile write.
+        evictOxyIdentityCache(this, id);
         this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
         return result;
       } catch (error) {

package/src/mixins/__tests__/accounts.test.ts

@@ -47,6 +47,7 @@ const memberFixture: AccountMember = {
   permissions: ['account:read', 'apps:read'],
   inherit: true,
   status: 'active',
+  source: 'direct',
   createdAt: '2026-06-29T00:00:00.000Z',
   updatedAt: '2026-06-29T00:00:00.000Z',
 };
@@ -385,6 +386,7 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/members');
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1');
+      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/accounts/');
     });
   });
 
@@ -403,6 +405,7 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/members');
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1');
+      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/accounts/');
     });
   });
 
@@ -421,6 +424,7 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/members');
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1');
+      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/accounts/');
     });
   });
 
@@ -439,6 +443,7 @@ describe('OxyServices.accounts', () => {
       );
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1/members');
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts/acc1');
+      expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/accounts/');
       expect(clearEntrySpy).toHaveBeenCalledWith('GET:/accounts');
       expect(clearPrefixSpy).toHaveBeenCalledWith('GET:/accounts?');
     });