@oxyhq/core 18.0.0 → 19.1.0

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

@@ -0,0 +1,128 @@
+/**
+ * Follow Graph Mixin Tests
+ *
+ * `makeRequest` is stubbed, so what these assert is the CONTRACT this mixin
+ * offers the applications above it: which request each method makes, and — the
+ * part worth a test rather than a comment — the things it must never send.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+describe('OxyServices.followGraph', () => {
+  let oxy: OxyServices;
+  let makeRequest: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    oxy.httpService.setTokens('test-token');
+    makeRequest = jest.spyOn(oxy, 'makeRequest').mockResolvedValue({} as never);
+  });
+
+  afterEach(() => {
+    makeRequest.mockRestore();
+  });
+
+  describe('the identities the client must not be able to state', () => {
+    it('never sends a follower id', async () => {
+      await oxy.followTarget('target-1');
+      await oxy.unfollowTarget('rel-1');
+      await oxy.listFollows();
+
+      // A client that could name the follower could forge a follow on somebody
+      // else's behalf. The server derives it from the session; there must be no
+      // parameter here that even looks like an alternative.
+      for (const call of makeRequest.mock.calls) {
+        expect(JSON.stringify(call)).not.toMatch(/user_?[Ii]d|follower/);
+      }
+    });
+
+    it('sends no application id unless the caller explicitly names another app', async () => {
+      await oxy.setFollowApplicationMode('rel-1', 'disabled');
+
+      // The ordinary case is "this application", derived server-side. Sending an
+      // id here by default would make every app's own writes indistinguishable
+      // from one app acting on another's behalf, which is the privileged
+      // operation.
+      expect(makeRequest.mock.calls[0][2]).toEqual({ mode: 'disabled' });
+    });
+
+    it('passes an explicitly named application through, for the privileged path', async () => {
+      await oxy.setFollowApplicationMode('rel-1', 'enabled', 'app-9');
+      expect(makeRequest.mock.calls[0][2]).toEqual({ mode: 'enabled', applicationId: 'app-9' });
+
+      await oxy.restoreFollowInheritance('rel-1', 'app-9');
+      expect(makeRequest.mock.calls[1][1]).toContain('applicationId=app-9');
+    });
+  });
+
+  describe('request shapes', () => {
+    it('follows with PUT and no body when the follow is permanent', async () => {
+      await oxy.followTarget('target-1');
+      const [method, path, body] = makeRequest.mock.calls[0];
+      expect(method).toBe('PUT');
+      expect(path).toBe('/v2/follows/target-1');
+      expect(body).toEqual({});
+    });
+
+    it('carries expiresIn for a timed follow', async () => {
+      await oxy.followTarget('target-1', { expiresIn: 72 * 60 * 60 });
+      expect(makeRequest.mock.calls[0][2]).toEqual({ expiresIn: 259200 });
+    });
+
+    it('unfollows by relationship id, not by target', async () => {
+      // The relationship is the thing that exists; addressing the unfollow by
+      // target would make the server re-derive which relationship was meant,
+      // and get it wrong for any target a user can follow more than one way.
+      await oxy.unfollowTarget('rel-1');
+      expect(makeRequest.mock.calls[0].slice(0, 2)).toEqual(['DELETE', '/v2/follows/rel-1']);
+    });
+
+    it('reads status per target', async () => {
+      await oxy.getFollowTargetStatus('target-1');
+      expect(makeRequest.mock.calls[0].slice(0, 2)).toEqual([
+        'GET',
+        '/v2/follows/target-1/status',
+      ]);
+    });
+
+    it('restores inheritance with no query string when the app means itself', async () => {
+      await oxy.restoreFollowInheritance('rel-1');
+      expect(makeRequest.mock.calls[0][1]).toBe('/v2/follows/rel-1/context');
+    });
+
+    it('paginates by cursor and filters by kind', async () => {
+      await oxy.listFollows({ kind: 'oxy.topic', cursor: '2026-01-01T00:00:00.000Z', limit: 20 });
+      const path = makeRequest.mock.calls[0][1] as string;
+      expect(path).toContain('kind=oxy.topic');
+      expect(path).toContain('limit=20');
+      expect(path).toContain('cursor=');
+      // Never an offset: the list changes while it is read, and an offset skips
+      // or repeats rows exactly when it does.
+      expect(path).not.toContain('offset');
+    });
+
+    it('escapes an id rather than letting it change the path', async () => {
+      await oxy.followTarget('../../admin');
+      expect(makeRequest.mock.calls[0][1]).toBe('/v2/follows/..%2F..%2Fadmin');
+    });
+  });
+
+  describe('caching', () => {
+    it('caches nothing', async () => {
+      await oxy.followTarget('t');
+      await oxy.getFollowTargetStatus('t');
+      await oxy.listFollows();
+      await oxy.unfollowTarget('r');
+      await oxy.setFollowApplicationMode('r', 'disabled');
+      await oxy.restoreFollowInheritance('r');
+
+      // A status cached across a write is the "follow reverts after navigating
+      // away and back" bug the legacy path had to fix with explicit
+      // invalidation. Not caching here leaves the app's own store as the single
+      // cache authority.
+      for (const call of makeRequest.mock.calls) {
+        expect(call[3]).toEqual({ cache: false });
+      }
+    });
+  });
+});

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

@@ -0,0 +1,407 @@
+/**
+ * Identity-cache invalidation for the profile WRITERS, against the REAL
+ * response cache.
+ *
+ * An account IS a user, and a profile screen never reads `/accounts/<id>` — it
+ * reads `GET /users/<id>` and `GET /profiles/username/<handle>`, both cached for
+ * five minutes in the caller's own process. `updateAccount` used to bust only
+ * the account-graph keys, so for up to five minutes after an edit a refetch
+ * handed back the PRE-EDIT profile from the client's own cache, with a
+ * perfectly healthy server ("I changed my channel's picture and it doesn't
+ * update until I reload the page").
+ *
+ * These tests drive the real `HttpService` cache over a mocked `fetch` rather
+ * than spying on `clearCacheEntry` / `clearCacheByPrefix`, because a spy proves
+ * only that SOME string was passed — not that the entry a read actually lands
+ * under was evicted. The load-bearing case is the RENAME: an implementation
+ * that busts the exact key for the handle in the write RESPONSE passes every
+ * assertion about the new handle while leaving the OLD handle's entry serving
+ * the pre-rename profile until its TTL. Both handles are warmed here so the two
+ * implementations disagree.
+ *
+ * `updateProfile` is covered here too, because it carried a SECOND, drifted
+ * hand-written copy of the same key list — it swept four of the six keys,
+ * missing `GET:/auth/lookup/` and `GET:/profiles/resolve`. Both writers now
+ * share one enumeration (`utils/identityCacheSweep`), and this is where that is
+ * asserted from the outside.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { AccountNode } from '../OxyServices.accounts';
+
+/**
+ * A non-verified JWT whose payload decodes to the given claims — enough for the
+ * cache's identity tag and the bearer preflight (`jwtDecode` never checks a
+ * signature).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url({
+    exp: Math.floor(Date.now() / 1000) + 3600,
+    ...payload,
+  })}.sig`;
+}
+
+/** A JSON `Response` in the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+const ACCOUNT_ID = 'acc1';
+const PARENT_ID = 'root1';
+const OLD_USERNAME = 'oldhandle';
+const NEW_USERNAME = 'newhandle';
+
+/** The write response: the account after a rename + a new picture. */
+const renamedNode: AccountNode = {
+  accountId: ACCOUNT_ID,
+  kind: 'channel',
+  parentAccountId: PARENT_ID,
+  account: {
+    id: ACCOUNT_ID,
+    publicKey: 'pk-acc1',
+    username: NEW_USERNAME,
+    name: { displayName: 'Renamed Channel' },
+    avatar: 'file_new',
+  },
+  relationship: 'owner',
+  callerMembership: null,
+};
+
+describe('updateAccount identity-cache invalidation (real cache)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+    oxy = new OxyServices({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+    oxy.httpService.setTokens(makeJwt({ userId: 'operator-1' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  /**
+   * Warm every cache entry an account can be served under, plus one unrelated
+   * entry that must SURVIVE. Returns the number of network calls made, so each
+   * assertion below can be expressed as "did this read hit the network again".
+   */
+  async function warmCaches(): Promise<number> {
+    // The profile screen's two reads, under the handle it had BEFORE the edit
+    // and under the id.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.getUserById(ACCOUNT_ID);
+
+    // The handle the account is ABOUT to be renamed to may already be warm (a
+    // 404-shaped read, a previous holder, a same-session preview). Warming it
+    // is what makes the old-handle assertion below non-vacuous: an
+    // implementation that busts only the response's handle passes for this one.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.getProfileByUsername(NEW_USERNAME);
+
+    // The pre-session login lookup (carries avatar + display name) and handle
+    // resolution — two keys the SDK's own profile-write sweep had drifted away
+    // from, and which no test previously covered from a write.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: OLD_USERNAME }));
+    await oxy.lookupUsername(OLD_USERNAME);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: OLD_USERNAME }));
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+
+    // The account-graph reads.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.getAccount(ACCOUNT_ID);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listAccounts();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listChildAccounts(PARENT_ID);
+
+    // An unrelated cached read. It must survive — the vacuity floor that tells
+    // a targeted sweep from a blanket `clearCache()`.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ count: 3 }));
+    await oxy.httpService.get('/notifications/unread-count', { cache: true });
+
+    return fetchMock.mock.calls.length;
+  }
+
+  /** Perform the rename + picture change. */
+  async function performUpdate(): Promise<void> {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.updateAccount(ACCOUNT_ID, {
+      username: NEW_USERNAME,
+      avatar: 'file_new',
+    });
+  }
+
+  it('warms every read it later asserts on (control: all are cache hits before the write)', async () => {
+    const warmed = await warmCaches();
+
+    // Re-issue every read with no queued response. A cache MISS would call
+    // `fetch`, which now resolves `undefined` and throws — so a green run here
+    // is proof that each entry really is resident, and that the assertions
+    // below are measuring eviction rather than a cache that was never warm.
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    await oxy.getProfileByUsername(NEW_USERNAME);
+    await oxy.getUserById(ACCOUNT_ID);
+    await oxy.lookupUsername(OLD_USERNAME);
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+    await oxy.getAccount(ACCOUNT_ID);
+    await oxy.listAccounts();
+    await oxy.listChildAccounts(PARENT_ID);
+    await oxy.httpService.get('/notifications/unread-count', { cache: true });
+
+    expect(fetchMock).toHaveBeenCalledTimes(warmed);
+  });
+
+  it('evicts the OLD handle, not just the handle in the write response', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // THE assertion. `updateAccount` cannot know the pre-rename handle — it is
+    // in neither the request nor the response — so only a PREFIX sweep of
+    // `GET:/profiles/username/` reaches it. A targeted `clearCacheEntry` for
+    // the response's handle leaves this entry serving the pre-rename profile.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    const refetched = await oxy.getProfileByUsername(OLD_USERNAME);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+    expect(refetched.username).toBe(NEW_USERNAME);
+  });
+
+  it('evicts the by-id profile read the account detail page uses', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, avatar: 'file_new' }));
+    const refetched = await oxy.getUserById(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+    expect(refetched.avatar).toBe('file_new');
+  });
+
+  it('evicts the new handle, the login lookup, and handle resolution', async () => {
+    await warmCaches();
+    await performUpdate();
+    let calls = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.getProfileByUsername(NEW_USERNAME);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: false, username: OLD_USERNAME }));
+    await oxy.lookupUsername(OLD_USERNAME);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, username: NEW_USERNAME }));
+    await oxy.resolveProfile(`@${OLD_USERNAME}@test.invalid`);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+  });
+
+  it('evicts the account detail, the account lists, and the PARENT children list', async () => {
+    await warmCaches();
+    await performUpdate();
+    let calls = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: renamedNode }));
+    await oxy.getAccount(ACCOUNT_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listAccounts();
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+
+    // Keyed by the PARENT id, which is reachable only from the response node —
+    // the child's own id does not build this key.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ accounts: [renamedNode] }));
+    await oxy.listChildAccounts(PARENT_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(++calls);
+  });
+
+  it('leaves unrelated cached reads alone (it is a sweep, not a cache wipe)', async () => {
+    await warmCaches();
+    await performUpdate();
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // No queued response: a miss would call `fetch` and throw.
+    const cached = await oxy.httpService.get<{ count: number }>(
+      '/notifications/unread-count',
+      { cache: true },
+    );
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite);
+    expect(cached.count).toBe(3);
+  });
+
+  it('does not sweep when the write fails', async () => {
+    await warmCaches();
+    const warmed = fetchMock.mock.calls.length;
+
+    fetchMock.mockResolvedValueOnce(
+      new Response(JSON.stringify({ message: 'forbidden' }), {
+        status: 403,
+        headers: { 'content-type': 'application/json' },
+      }),
+    );
+    await expect(
+      oxy.updateAccount(ACCOUNT_ID, { avatar: 'file_new' }),
+    ).rejects.toThrow();
+
+    // The failed PATCH is one call; every read below must still be a cache hit.
+    await oxy.getProfileByUsername(OLD_USERNAME);
+    await oxy.getUserById(ACCOUNT_ID);
+    await oxy.getAccount(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(warmed + 1);
+  });
+
+  it('still sweeps the identity keys when the response carries no parent', async () => {
+    await warmCaches();
+    const rootNode: AccountNode = { ...renamedNode, parentAccountId: null };
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: rootNode }));
+    await oxy.updateAccount(ACCOUNT_ID, { avatar: 'file_new' });
+    const afterWrite = fetchMock.mock.calls.length;
+
+    // A root account has no children list to bust, but its identity keys go
+    // stale exactly the same way — the `parentAccountId` guard must not gate
+    // the identity sweep.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: ACCOUNT_ID, avatar: 'file_new' }));
+    await oxy.getUserById(ACCOUNT_ID);
+
+    expect(fetchMock).toHaveBeenCalledTimes(afterWrite + 1);
+  });
+});
+
+describe('updateProfile identity-cache invalidation (real cache)', () => {
+  let originalFetch: typeof globalThis.fetch;
+  let fetchMock: jest.Mock<Promise<Response>, [RequestInfo | URL, RequestInit?]>;
+  let oxy: OxyServices;
+
+  const SELF_ID = 'me-1';
+
+  beforeEach(() => {
+    originalFetch = globalThis.fetch;
+    fetchMock = jest.fn();
+    globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+    oxy = new OxyServices({
+      baseURL: 'http://test.invalid',
+      enableRetry: false,
+      requestTimeout: 1000,
+    });
+    oxy.httpService.setTokens(makeJwt({ userId: SELF_ID }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  /**
+   * The two keys `updateProfile`'s own hand-written sweep MISSED. They are the
+   * whole point of this block — a test that only re-checked `GET:/users/me` and
+   * `GET:/profiles/username/` would have passed against the drifted version.
+   */
+  it('evicts the login lookup and handle resolution, not just the keys it used to know', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: 'alice', avatar: 'old' }));
+    await oxy.lookupUsername('alice');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.resolveProfile('@alice@test.invalid');
+
+    // Control: both are warm (a miss would call the un-queued mock and throw).
+    await oxy.lookupUsername('alice');
+    await oxy.resolveProfile('@alice@test.invalid');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.updateProfile({ avatar: 'new' });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ exists: true, username: 'alice', avatar: 'new' }));
+    await oxy.lookupUsername('alice');
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.resolveProfile('@alice@test.invalid');
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('still evicts the self, by-id and handle reads it always did', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getCurrentUser();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getUserById(SELF_ID);
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getProfileByUsername('alice');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'old' }));
+    await oxy.getUserBySession('sess-1');
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.updateProfile({ avatar: 'new' });
+
+    let calls = 5;
+    for (const read of [
+      () => oxy.getCurrentUser(),
+      () => oxy.getUserById(SELF_ID),
+      () => oxy.getProfileByUsername('alice'),
+      () => oxy.getUserBySession('sess-1'),
+    ]) {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+      await read();
+      expect(fetchMock).toHaveBeenCalledTimes(++calls);
+    }
+  });
+
+  it('evicts the account forest list and detail after a self-profile edit', async () => {
+    const selfNode: AccountNode = {
+      accountId: SELF_ID,
+      kind: 'personal',
+      parentAccountId: null,
+      account: {
+        id: SELF_ID,
+        publicKey: 'pk-me',
+        username: 'alice',
+        name: { displayName: 'Alice' },
+        avatar: 'old',
+      },
+      relationship: 'self',
+      callerMembership: null,
+    };
+
+    fetchMock.mockResolvedValueOnce(jsonResponse([selfNode]));
+    await oxy.listAccounts();
+    fetchMock.mockResolvedValueOnce(jsonResponse({ account: selfNode }));
+    await oxy.getAccount(SELF_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ id: SELF_ID, avatar: 'new' }));
+    await oxy.updateProfile({ avatar: 'new' });
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse([{ ...selfNode, account: { ...selfNode.account!, avatar: 'new' } }]));
+    await oxy.listAccounts();
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({ account: { ...selfNode, account: { ...selfNode.account!, avatar: 'new' } } }),
+    );
+    await oxy.getAccount(SELF_ID);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+});

package/src/mixins/index.ts

@@ -30,6 +30,7 @@ import { OxyServicesAppDataMixin } from './OxyServices.appData';
 import { OxyServicesCivicMixin } from './OxyServices.civic';
 import { OxyServicesNodesMixin } from './OxyServices.nodes';
 import { OxyServicesLinksMixin } from './OxyServices.links';
+import { OxyServicesFollowGraphMixin } from './OxyServices.followGraph';
 import { OxyServicesDeviceBootMixin } from './OxyServices.deviceBoot';
 import { OxyServicesDeviceTransferMixin } from './OxyServices.deviceTransfer';
 
@@ -66,6 +67,7 @@ type AllMixinInstances =
   & InstanceType<ReturnType<typeof OxyServicesCivicMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesNodesMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesLinksMixin<typeof OxyServicesBase>>>
+  & InstanceType<ReturnType<typeof OxyServicesFollowGraphMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceBootMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesDeviceTransferMixin<typeof OxyServicesBase>>>
   & InstanceType<ReturnType<typeof OxyServicesUtilityMixin<typeof OxyServicesBase>>>;
@@ -141,6 +143,9 @@ const MIXIN_PIPELINE: MixinFunction[] = [
     // 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`).

package/src/models/interfaces.ts

@@ -1,6 +1,6 @@
 import type {
   AccountKind,
-  OrganizationCategory,
+  AccountCategoryId,
   UserNameResponse,
   UserRelationship,
   ThemePreference,
@@ -170,8 +170,16 @@ export interface User {
   // Managed account fields
   isManagedAccount?: boolean;
   managedBy?: string;
-  /** Real-estate taxonomy when this user is a `kind: 'organization'` account. */
-  organizationCategory?: OrganizationCategory;
+  /**
+   * What this account is about, for any NON-personal account. ORDERED — the
+   * first element is the primary category, and nothing may reorder it.
+   *
+   * Stable ids, not labels: render each through the
+   * `accounts.accountCategory.<id>` translation key so the reader sees their own
+   * language rather than the language of whoever chose it. Absent when the
+   * account has none.
+   */
+  accountCategories?: AccountCategoryId[];
   /**
    * The account's languages as full BCP-47 locales (`language-REGION`, e.g.
    * `en-US`, `es-MX`, `pt-BR`), ordered with the PRIMARY (UI) locale first.

package/src/server/__tests__/userInvalidation.test.ts

@@ -2,10 +2,11 @@ import { OXY_USER_INVALIDATION_CHANNEL } from '@oxyhq/contracts';
 
 import {
   createOxyUserInvalidationHandler,
-  evictOxyIdentityCache,
   publishOxyUserInvalidation,
-  type OxyIdentityCacheEvictor,
 } from '../userInvalidation';
+// The key enumeration this subscriber sweeps is platform-neutral and shared
+// with the client mixins — see `utils/identityCacheSweep` and its own suite.
+import type { OxyIdentityCacheEvictor } from '../../utils/identityCacheSweep';
 
 function makePublisher() {
   const calls: Array<{ channel: string; message: string }> = [];
@@ -200,21 +201,3 @@ describe('@oxyhq/core/server createOxyUserInvalidationHandler', () => {
     expect(() => createOxyUserInvalidationHandler()(validMessage)).not.toThrow();
   });
 });
-
-describe('@oxyhq/core/server evictOxyIdentityCache', () => {
-  it('clears the exact by-id entry and the handle-keyed prefixes', () => {
-    // The by-id key is exact. The handle-keyed ones cannot be derived from an
-    // id without the lookup being invalidated, so they are swept by prefix.
-    const { evictor, entries, prefixes } = makeEvictor();
-    evictOxyIdentityCache(evictor, 'abc123');
-
-    expect(entries).toEqual(['GET:/users/abc123']);
-    expect(prefixes).toEqual([
-      'GET:/session/user/',
-      'GET:/users/me',
-      'GET:/auth/lookup/',
-      'GET:/profiles/username/',
-      'GET:/profiles/resolve',
-    ]);
-  });
-});

package/src/server/index.ts

@@ -86,14 +86,17 @@ export { verifySecret } from './verifySecret';
 // changes, every consuming backend sweeps its caches instead of waiting out a TTL.
 export {
   createOxyUserInvalidationHandler,
-  evictOxyIdentityCache,
   publishOxyUserInvalidation,
 } from './userInvalidation';
 export type {
-  OxyIdentityCacheEvictor,
   OxyInvalidationPublisher,
   OxyUserInvalidationHandlerOptions,
 } from './userInvalidation';
+// 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';
+export type { OxyIdentityCacheEvictor } from '../utils/identityCacheSweep';
 
 // 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.