@oxyhq/core 18.0.0 → 19.1.0

package/dist/esm/mixins/OxyServices.followGraph.js

@@ -0,0 +1,201 @@
+/**
+ * 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 { buildUrl } from '../utils/apiUtils.js';
+export function OxyServicesFollowGraphMixin(Base) {
+    return class extends Base {
+        constructor(...args) {
+            super(...args);
+        }
+        /**
+         * 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, options) {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                return await this.makeRequest('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) {
+            try {
+                return await this.makeRequest('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, mode, applicationId) {
+            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, applicationId) {
+            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) {
+            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) {
+            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) {
+            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) {
+            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('GET', path, undefined, { cache: false });
+            }
+            catch (error) {
+                throw this.handleError(error);
+            }
+        }
+    };
+}

package/dist/esm/mixins/OxyServices.user.js

@@ -3,6 +3,8 @@ import { buildQueryParams, buildPaginationParams, } from '../utils/apiUtils.js';
 import { KeyManager } from '../crypto/keyManager.js';
 import { SignatureService } from '../crypto/signatureService.js';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity.js';
+import { evictOxyIdentityCache } from '../utils/identityCacheSweep.js';
+import { evictOxyAccountForestCache } from '../utils/accountCacheSweep.js';
 import { logger } from '../logger/index.js';
 import { extractErrorStatus } from '../utils/errorUtils.js';
 /**
@@ -344,28 +346,24 @@ export function OxyServicesUserMixin(Base) {
         /**
          * 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.
          */
         async updateProfile(updates) {
             try {
                 const result = normalizeUserIdentity(await this.makeRequest('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) {
@@ -418,10 +416,9 @@ export function OxyServicesUserMixin(Base) {
                 const result = await this.makeRequest('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;
             }

package/dist/esm/mixins/index.js

@@ -29,6 +29,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData.js';
 import { OxyServicesCivicMixin } from './OxyServices.civic.js';
 import { OxyServicesNodesMixin } from './OxyServices.nodes.js';
 import { OxyServicesLinksMixin } from './OxyServices.links.js';
+import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph.js';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot.js';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer.js';
 /**
@@ -85,6 +86,9 @@ const MIXIN_PIPELINE = [
     // Link previews / unfurls: SDK-owned link-metadata resolution via oxy-api,
     // so apps stop scraping link metadata locally.
     OxyServicesLinksMixin,
+    // The user-owned follow graph (#809). One relationship per user and target,
+    // shared across applications, with per-application context on top.
+    OxyServicesFollowGraphMixin,
     // Device-first token mint: the client half of the zero-cookie transport
     // (`mintFromDeviceSecret` → `POST /session/device/token`).
     OxyServicesDeviceBootMixin,

package/dist/esm/server/index.js

@@ -27,7 +27,11 @@ export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders,
 export { verifySecret } from './verifySecret.js';
 // Cross-service user-invalidation signal: oxy-api publishes when identity
 // changes, every consuming backend sweeps its caches instead of waiting out a TTL.
-export { createOxyUserInvalidationHandler, evictOxyIdentityCache, publishOxyUserInvalidation, } from './userInvalidation.js';
+export { createOxyUserInvalidationHandler, publishOxyUserInvalidation, } from './userInvalidation.js';
+// The identity-key enumeration itself is platform-neutral (`src/utils/`) so the
+// client mixins and this Node-only subscriber sweep the SAME list — a second
+// copy is what let `updateAccount` and `updateProfile` drift apart.
+export { evictOxyIdentityCache, oxyUserByIdCacheKey, OXY_IDENTITY_CACHE_PREFIXES } from '../utils/identityCacheSweep.js';
 // Registrable-apex (eTLD+1) derivation via the Public Suffix List — the SINGLE
 // SOURCE OF TRUTH shared with the IdP worker and the client FAPI auto-detect.
 // Pure host handling (no browser deps), so it is safe on the server subpath and

package/dist/esm/server/userInvalidation.js

@@ -6,10 +6,10 @@
  * Every Oxy backend caches Oxy identity, and none of them find out when it
  * changes. The `OxyServices` GET response cache holds `GET /users/:id` and
  * `GET /profiles/username/:name` for five minutes; it is swept when THIS process
- * writes the profile (see the `clearCacheEntry` calls in the user mixin) and
- * never when somebody else does — which is the normal case, since profiles are
- * edited in Oxy's own apps. So an avatar or display-name change is invisible to
- * every consuming backend for up to five minutes, per process.
+ * writes the profile (the `evictOxyIdentityCache` calls in the user and accounts
+ * mixins) and never when somebody else does — which is the normal case, since
+ * profiles are edited in Oxy's own apps. So an avatar or display-name change is
+ * invisible to every consuming backend for up to five minutes, per process.
  *
  * oxy-api broadcasts {@link OXY_USER_INVALIDATION_CHANNEL} on the shared Valkey
  * when a user's identity changes. This module is the consumer half: it parses
@@ -51,6 +51,7 @@
  * Node-only; exported solely from `@oxyhq/core/server`.
  */
 import { OXY_USER_INVALIDATION_CHANNEL, isPublishedOxyUserChangeReason, oxyUserInvalidationEventSchema, } from '@oxyhq/contracts';
+import { evictOxyIdentityCache, } from '../utils/identityCacheSweep.js';
 /**
  * Broadcast that an Oxy user's record changed.
  *
@@ -149,25 +150,3 @@ export function createOxyUserInvalidationHandler(options = {}) {
         }
     };
 }
-/**
- * Sweep an `OxyServices` GET response cache of everything that could carry the
- * given user's identity.
- *
- * The by-id entry is exact. The by-username and resolve entries are keyed by
- * HANDLE, which cannot be derived from an id without the very lookup we are
- * invalidating, so those are swept by prefix — the same imprecision the SDK
- * already accepts when it sweeps its own cache after a local profile write, and
- * bounded by the fact that over-eviction costs a refetch and can never serve
- * wrong data.
- */
-export function evictOxyIdentityCache(oxy, userId) {
-    // Match the sweep the user mixin runs after a local profile write — session-
-    // bound and /users/me entries are keyed without the user id, so they must be
-    // prefix-swept on cross-service invalidation too.
-    oxy.clearCacheByPrefix('GET:/session/user/');
-    oxy.clearCacheByPrefix('GET:/users/me');
-    oxy.clearCacheByPrefix('GET:/auth/lookup/');
-    oxy.clearCacheEntry(`GET:/users/${userId}`);
-    oxy.clearCacheByPrefix('GET:/profiles/username/');
-    oxy.clearCacheByPrefix('GET:/profiles/resolve');
-}

package/dist/esm/session/accountProjection.js

@@ -19,6 +19,35 @@
 import { isActAsEligibleKind } from '@oxyhq/contracts';
 import { getAccountDisplayName, getAccountFallbackHandle } from '../utils/accountUtils.js';
 import { getNormalizedUserHandle } from '../utils/userHandle.js';
+/**
+ * Whether the caller can BECOME this account — the one question every account
+ * switcher asks, answered here so no surface has to re-derive it.
+ *
+ * Two independent grounds, either of which suffices:
+ *
+ *  - **It is already the caller's own identity** (`relationship: 'self'`).
+ *    `GET /accounts` resolves its caller through `resolveOperatorId`, so `self`
+ *    is the HUMAN operator's personal account even while they are operating an
+ *    org — never the operated account. Kind is irrelevant on this ground: the
+ *    caller IS that account, so returning to it asks the server for nothing.
+ *  - **The server will mint a session for it** — `isActAsEligibleKind(kind)` is
+ *    the exact predicate `POST /accounts/:id/switch` enforces, so a row offered
+ *    on this ground is never a dead button.
+ *
+ * `isActAsEligibleKind` ALONE is not this question, and reaching for it
+ * directly is the mistake this function exists to prevent: it is false for
+ * `personal` as well as `channel`, so a switcher gated on it alone renders an
+ * empty list rather than a filtered one. Equally, `kind !== 'channel'` is not
+ * this question either — it silently admits every kind invented after it was
+ * written, which is the same trap `isActAsEligibleKind` was introduced to close
+ * on the server.
+ *
+ * Takes a structural subset rather than a whole {@link AccountNode} so a caller
+ * holding a projected {@link SwitchableAccount} can ask it too.
+ */
+export function isSwitchTargetAccount(node) {
+    return node.relationship === 'self' || isActAsEligibleKind(node.kind);
+}
 /**
  * Pure union of device sign-ins and account-graph nodes into the flat
  * {@link SwitchableAccount}[] every switcher renders.
@@ -28,8 +57,9 @@ import { getNormalizedUserHandle } from '../utils/userHandle.js';
  * and a graph node is deduped into ONE device row enriched with the graph
  * metadata (relationship / kind / parent / membership).
  *
- * Graph nodes of a kind nobody may act as (`channel`) are omitted — see the
- * filter below.
+ * Graph nodes that are not switch targets — a `channel`, which nobody may act
+ * as — are omitted. {@link isSwitchTargetAccount} is the rule; see the filter
+ * below.
  */
 export function projectSwitchableAccounts(input) {
     const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -104,10 +134,12 @@ export function projectSwitchableAccounts(input) {
         // construction": the graph contributes accounts that have no device session
         // and no credentials at all, which is exactly how an org first becomes
         // switchable. So a kind that must never be switched into has to be filtered
-        // HERE, and `isActAsEligibleKind` is the same predicate the server enforces
-        // on `POST /accounts/:id/switch` — offering a row the server would 403 is a
-        // dead button.
-        if (!isActAsEligibleKind(node.kind)) {
+        // HERE — offering a row the server would 403 is a dead button.
+        //
+        // An account already on the device skipped this check via the branch above,
+        // and correctly: whatever its kind, the caller is signed into it, so
+        // switching is a local activation that asks the server for nothing.
+        if (!isSwitchTargetAccount(node)) {
             continue;
         }
         remember(toRow(node.account, {
@@ -129,8 +161,11 @@ export function projectSwitchableAccounts(input) {
  * document, but including their ids lets the caller pass one id set and lets the
  * projection prefer freshly-fetched profiles uniformly.
  *
- * Applies the SAME act-as filter as {@link projectSwitchableAccounts} to graph
- * nodes, so this never fetches a profile for a row the projection will drop.
+ * Applies the SAME {@link isSwitchTargetAccount} filter as
+ * {@link projectSwitchableAccounts} to graph nodes, so this never fetches a
+ * profile for a row the projection will drop — and, just as importantly, never
+ * SKIPS one the projection will keep, which would leave that row unrendered
+ * until some later fetch happened to resolve it.
  */
 export function switchableAccountIds(state, graph) {
     const ids = new Set();
@@ -140,7 +175,7 @@ export function switchableAccountIds(state, graph) {
         }
     }
     for (const node of graph) {
-        if (node.accountId && isActAsEligibleKind(node.kind)) {
+        if (node.accountId && isSwitchTargetAccount(node)) {
             ids.add(node.accountId);
         }
     }

package/dist/esm/utils/accountCacheSweep.js

@@ -0,0 +1,75 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that serve the ACCOUNT FOREST
+ * — the caller's accessible accounts, as lists and as individual detail rows —
+ * and the one sweep that clears them.
+ *
+ * WHY THIS IS NOT A METHOD ON THE ACCOUNTS MIXIN
+ * ---------------------------------------------
+ * `AccountNode.account` is a whole `User`, so a forest read embeds the very
+ * profile the identity reads serve. That makes an IDENTITY write a writer of
+ * these keys too: `updateProfile` edits the caller's own personal account,
+ * which is a row in `GET /accounts` and is its own `GET /accounts/<id>`. Leave
+ * those cached and the account switcher keeps drawing the pre-edit name and
+ * picture for the full TTL, against a perfectly healthy server.
+ *
+ * The mixins compose into one class at runtime but are typed one at a time, so
+ * the user mixin cannot call a method the accounts mixin owns. The key list
+ * therefore lives here, once, and every writer calls {@link
+ * evictOxyAccountForestCache} — exactly like the identity key list in
+ * `identityCacheSweep`, which the accounts mixin already calls for the
+ * mirror-image case (an account write staling the identity reads). The
+ * alternative — a second hand-written copy of these keys in the other mixin —
+ * is the drift that shipped the two stale-profile bugs `identityCacheSweep`
+ * documents.
+ *
+ * WHY THE LIST NEEDS A PREFIX AND THE DETAIL DOES NOT
+ * --------------------------------------------------
+ * `listAccounts({tree?})` keys the flat list as `GET:/accounts` and every
+ * option variant as `GET:/accounts?<query>` (the query string is part of the
+ * URL, hence of the key), and a writer cannot enumerate which variants a caller
+ * has read. The detail key, by contrast, is derivable from the account id the
+ * writer already holds.
+ *
+ * The `GET:/accounts?` prefix matches ONLY the query-string list variants —
+ * never `GET:/accounts/<id>` or its `…/members`, `…/credentials`, `…/children`
+ * sub-resources, which are the accounts mixin's own business and stay there.
+ */
+/** The cache key `listAccounts()` reads under with no options. */
+export const OXY_ACCOUNT_LIST_CACHE_KEY = 'GET:/accounts';
+/**
+ * The prefix covering every option-carrying `listAccounts(opts)` variant
+ * (`?tree=true`, …), none of which a writer can enumerate.
+ */
+export const OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX = 'GET:/accounts?';
+/**
+ * Prefix covering every per-account sub-resource cache key
+ * (`GET:/accounts/<id>`, `…/members`, `…/credentials`, `…/children`). A
+ * membership mutation on an ancestor must sweep ALL of these, not only the
+ * account named in the path: descendant member rosters embed inherited rows
+ * resolved from that ancestor, and the writer cannot enumerate which descendant
+ * ids a caller has already read. The trailing slash deliberately excludes the
+ * forest list keys (`GET:/accounts`, `GET:/accounts?…`) documented above.
+ */
+export const OXY_ACCOUNT_PER_ACCOUNT_CACHE_PREFIX = 'GET:/accounts/';
+/**
+ * Build the exact cache key `getAccount(accountId)` reads under.
+ */
+export function oxyAccountDetailCacheKey(accountId) {
+    return `GET:/accounts/${encodeURIComponent(accountId)}`;
+}
+/**
+ * Sweep an `OxyServices` GET response cache of the account forest.
+ *
+ * @param oxy       - Anything exposing the SDK's two eviction methods.
+ * @param accountId - The account whose detail row to drop as well. Optional: a
+ *                    writer that changed the SHAPE of the forest rather than one
+ *                    account in it (create, archive, ownership transfer) has no
+ *                    detail row to name, and clears only the lists.
+ */
+export function evictOxyAccountForestCache(oxy, accountId) {
+    oxy.clearCacheEntry(OXY_ACCOUNT_LIST_CACHE_KEY);
+    oxy.clearCacheByPrefix(OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
+    if (accountId) {
+        oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+    }
+}

package/dist/esm/utils/identityCacheSweep.js

@@ -0,0 +1,92 @@
+/**
+ * THE enumeration of `OxyServices` GET-cache keys that can carry a single
+ * account's identity, and the one sweep that clears them.
+ *
+ * WHY THIS IS ONE LIST
+ * --------------------
+ * An Oxy account is readable under SEVERAL cache keys, and a write that only
+ * busts the key it happens to know about leaves every other one serving the
+ * pre-write snapshot for up to its TTL — from the caller's OWN in-memory cache,
+ * with a perfectly healthy server. That failure has already shipped twice with
+ * two different sets of keys:
+ *
+ *   - `updateAccount` busted `GET:/accounts/<id>` and the account lists, but a
+ *     profile screen reads `GET:/profiles/username/<name>` and
+ *     `GET:/users/<id>`, so a channel's new picture stayed invisible for the
+ *     full 5-minute profile TTL.
+ *   - `updateProfile` busted four of the six keys below, missing
+ *     `GET:/auth/lookup/` (the login-flow avatar/display-name lookup) and
+ *     `GET:/profiles/resolve` (handle resolution) — two independently-drifted
+ *     copies of a list that has to agree.
+ *
+ * So the list lives here, once, and every writer calls
+ * {@link evictOxyIdentityCache}. Adding a new identity read means adding its key
+ * HERE and every writer inherits it.
+ *
+ * WHERE THE LINE IS DRAWN
+ * -----------------------
+ * These are the SINGLE-PROFILE reads — the account is the subject of the
+ * response and is addressable by id, handle, or session. Reads that merely
+ * CONTAIN an account among many (`GET:/profiles/search`,
+ * `GET:/users/<other>/followers`, `GET:/profiles/<other>/similar`) are
+ * deliberately NOT swept: an account cannot be located in them without the very
+ * lookup being invalidated, so sweeping them means sweeping the whole namespace
+ * on every identity change — a real cost on a backend consuming the
+ * cross-service invalidation signal, for a surface where a stale thumbnail
+ * expires on its own in ~2 minutes.
+ *
+ * WHY PREFIXES RATHER THAN EXACT KEYS
+ * -----------------------------------
+ * Only the by-id key can be built from a user id. The handle-keyed and
+ * session-keyed entries cannot — deriving a handle from an id needs the lookup
+ * we are invalidating, and the SDK never tracks active session ids centrally.
+ * Prefix sweeping is also what makes a USERNAME CHANGE correct: the entry under
+ * the OLD handle is unreachable by construction (nothing in the write response
+ * carries it), and a sweep targeted at the new handle alone would leave the old
+ * one serving the pre-rename profile until its TTL. Over-eviction costs a
+ * refetch; under-eviction serves wrong data.
+ *
+ * Platform-neutral by construction (no imports, no `OxyServices` reference) so
+ * the client mixins and the Node-only `@oxyhq/core/server` invalidation
+ * subscriber can share it without either pulling in the other.
+ */
+/**
+ * Cache-key PREFIXES under which an account's identity can be served, for the
+ * reads whose key cannot be derived from a user id. Swept wholesale.
+ */
+export const OXY_IDENTITY_CACHE_PREFIXES = [
+    // `getUserBySession` — keyed by session id, which the SDK never enumerates.
+    'GET:/session/user/',
+    // `getCurrentUser` (and `GET:/users/me/graph`, harmlessly included).
+    'GET:/users/me',
+    // `lookupUsername` — the pre-session login lookup; carries avatar + display name.
+    'GET:/auth/lookup/',
+    // `getProfileByUsername` — keyed by handle, including the pre-rename handle.
+    'GET:/profiles/username/',
+    // `resolveProfile` — keyed by fediverse handle in the query payload.
+    'GET:/profiles/resolve',
+];
+/**
+ * Build the exact cache key `getUserById` reads under. The only identity key
+ * derivable from a user id, so the only one that does not need a prefix sweep.
+ */
+export function oxyUserByIdCacheKey(userId) {
+    return `GET:/users/${userId}`;
+}
+/**
+ * Sweep an `OxyServices` GET response cache of everything that could carry the
+ * given account's identity.
+ *
+ * @param oxy    - Anything exposing the SDK's two eviction methods.
+ * @param userId - The account whose by-id entry to drop. Optional: a caller
+ *                 that does not know the id still clears every handle-, session-
+ *                 and self-keyed entry, which is the majority of the surface.
+ */
+export function evictOxyIdentityCache(oxy, userId) {
+    for (const prefix of OXY_IDENTITY_CACHE_PREFIXES) {
+        oxy.clearCacheByPrefix(prefix);
+    }
+    if (userId) {
+        oxy.clearCacheEntry(oxyUserByIdCacheKey(userId));
+    }
+}