@oxyhq/core 19.0.0 → 19.1.0

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

@@ -367,4 +367,41 @@ describe('updateProfile identity-cache invalidation (real cache)', () => {
       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/session/__tests__/accountProjection.test.ts

@@ -1,7 +1,9 @@
 import type { DeviceSessionState } from '@oxyhq/contracts';
+import { ACCOUNT_KINDS } from '@oxyhq/contracts';
 import type { User } from '../../models/interfaces';
 import type { AccountNode } from '../../mixins/OxyServices.accounts';
 import {
+  isSwitchTargetAccount,
   projectSwitchableAccounts,
   switchableAccountIds,
 } from '../accountProjection';
@@ -49,6 +51,57 @@ const mapOf = (...users: User[]): Map<string, User> => {
 
 const noAvatar = (): undefined => undefined;
 
+describe('isSwitchTargetAccount', () => {
+  /**
+   * EXHAUSTIVE over `ACCOUNT_KINDS`, as one object equality rather than a
+   * per-kind assertion, for two reasons that a `channel → false` spot-check
+   * cannot give:
+   *
+   *  - It distinguishes "excludes channels" from "excludes everything". Three
+   *    kinds must come back `true` here, so a predicate that answered `false`
+   *    unconditionally — the shape that empties a switcher instead of filtering
+   *    it — fails on those three, not on the channel.
+   *  - Adding a sixth kind fails this test with a missing key, forcing the
+   *    decision to be made HERE rather than inherited silently from whichever
+   *    literal comparison happened to be written first.
+   */
+  it('answers by kind for an account the caller merely owns or is a member of', () => {
+    expect(
+      Object.fromEntries(
+        ACCOUNT_KINDS.map((kind) => [kind, isSwitchTargetAccount({ kind, relationship: 'owner' })]),
+      ),
+    ).toEqual({
+      personal: false,
+      organization: true,
+      project: true,
+      bot: true,
+      channel: false,
+    });
+  });
+
+  /**
+   * The `self` ground, and the reason this predicate is not `isActAsEligibleKind`.
+   *
+   * `personal` is act-as INELIGIBLE — assuming somebody's human login would be
+   * impersonation — so a switcher gated on that predicate alone would drop the
+   * caller's OWN account and render an empty list. `GET /accounts` resolves its
+   * caller through `resolveOperatorId`, so a `self` node is always the human
+   * operator's own personal account, even while they operate an org.
+   */
+  it('admits the caller’s own personal account, which is act-as ineligible', () => {
+    expect(isSwitchTargetAccount({ kind: 'personal', relationship: 'self' })).toBe(true);
+    // Same kind, not the caller's own → refused. The `relationship` is doing the
+    // work, so neither half of the predicate can be deleted without a failure.
+    expect(isSwitchTargetAccount({ kind: 'personal', relationship: 'member' })).toBe(false);
+  });
+
+  it('refuses an account with no kind information rather than assuming', () => {
+    expect(isSwitchTargetAccount({})).toBe(false);
+    expect(isSwitchTargetAccount({ kind: null })).toBe(false);
+    expect(isSwitchTargetAccount({ kind: undefined, relationship: 'owner' })).toBe(false);
+  });
+});
+
 describe('projectSwitchableAccounts', () => {
   it('returns [] for null state and empty graph', () => {
     expect(
@@ -138,6 +191,50 @@ describe('projectSwitchableAccounts', () => {
     expect(rows.some((r) => r.kind === 'channel')).toBe(false);
   });
 
+  /**
+   * The same rule as the `isSwitchTargetAccount` matrix above, asserted through
+   * the projection so the WIRING is covered and not just the predicate.
+   *
+   * The fixture deliberately carries one graph-only node of every kind, and
+   * FOUR of the five must survive: a fixture list of channels alone could not
+   * tell "omits channels" from "omits every graph-only row", which is the
+   * failure mode that would silently empty an operator's switcher of the orgs
+   * they actually work in. `a1` is a device row and is asserted separately, so
+   * the graph lane's output is never confused with the device lane's.
+   */
+  it('keeps every switchable kind while dropping the channel (graph lane)', () => {
+    const rows = projectSwitchableAccounts({
+      state: state([{ accountId: 'a1', sessionId: 's1' }], 'a1'),
+      graph: [
+        graphNode('self1', { kind: 'personal', relationship: 'self' }),
+        graphNode('org1', { kind: 'organization' }),
+        graphNode('proj1', { kind: 'project' }),
+        graphNode('bot1', { kind: 'bot' }),
+        graphNode('chan1', { kind: 'channel' }),
+      ],
+      profilesById: mapOf(
+        user('a1'),
+        user('self1'),
+        user('org1'),
+        user('proj1'),
+        user('bot1'),
+        user('chan1'),
+      ),
+      resolveAvatarUrl: noAvatar,
+    });
+
+    expect(rows.map((r) => r.accountId)).toEqual(['a1', 'self1', 'org1', 'proj1', 'bot1']);
+    // Stated the other way round too, so a fixture that stopped reaching the
+    // graph lane at all could not pass this as a vacuous "no channels found".
+    expect(rows.map((r) => r.kind)).toEqual([
+      undefined,
+      'personal',
+      'organization',
+      'project',
+      'bot',
+    ]);
+  });
+
   it('dedups an account present as BOTH device session and graph node into ONE enriched row', () => {
     const rows = projectSwitchableAccounts({
       state: state([{ accountId: 'a1', sessionId: 's1', authuser: 0 }], 'a1'),
@@ -232,11 +329,21 @@ describe('switchableAccountIds', () => {
     expect(switchableAccountIds(null, [])).toEqual([]);
   });
 
-  it('omits a graph-only channel, so no profile is fetched for a dropped row', () => {
+  /**
+   * Must stay in lockstep with the projection's own filter in BOTH directions:
+   * an id fetched for a dropped row is wasted work, but an id NOT fetched for a
+   * row the projection keeps is worse — that row has no profile, so the
+   * projection's device lane skips it and it silently never renders.
+   */
+  it('applies the same switch-target filter as the projection', () => {
     const ids = switchableAccountIds(null, [
+      graphNode('self1', { kind: 'personal', relationship: 'self' }),
       graphNode('org1', { kind: 'organization' }),
+      graphNode('proj1', { kind: 'project' }),
+      graphNode('bot1', { kind: 'bot' }),
       graphNode('chan1', { kind: 'channel' }),
+      graphNode('other1', { kind: 'personal', relationship: 'member' }),
     ]);
-    expect(ids).toEqual(['org1']);
+    expect(ids).toEqual(['bot1', 'org1', 'proj1', 'self1']);
   });
 });

package/src/session/accountProjection.ts

@@ -103,6 +103,38 @@ export interface SwitchableAccount {
   user: SwitchableAccountUser;
 }
 
+/**
+ * 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: { kind?: AccountKind | null; relationship?: AccountRelationship },
+): boolean {
+  return node.relationship === 'self' || isActAsEligibleKind(node.kind);
+}
+
 /** Input to {@link projectSwitchableAccounts}. */
 export interface ProjectSwitchableAccountsInput {
   /**
@@ -144,8 +176,9 @@ export interface ProjectSwitchableAccountsInput {
  * 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: ProjectSwitchableAccountsInput): SwitchableAccount[] {
   const { state, graph, profilesById, activeUser, locale, resolveAvatarUrl } = input;
@@ -236,10 +269,12 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
     // 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, {
@@ -263,8 +298,11 @@ export function projectSwitchableAccounts(input: ProjectSwitchableAccountsInput)
  * 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: DeviceSessionState | null,
@@ -277,7 +315,7 @@ export function switchableAccountIds(
     }
   }
   for (const node of graph) {
-    if (node.accountId && isActAsEligibleKind(node.kind)) {
+    if (node.accountId && isSwitchTargetAccount(node)) {
       ids.add(node.accountId);
     }
   }

package/src/utils/accountCacheSweep.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+import type { OxyIdentityCacheEvictor } from './identityCacheSweep';
+
+/**
+ * The cache-eviction surface of an `OxyServices` instance. Reused from
+ * `identityCacheSweep` rather than re-declared: it is the SDK's one published
+ * name for these two methods, and a second identical interface would be one
+ * more shape to keep in step.
+ */
+export type OxyAccountCacheEvictor = OxyIdentityCacheEvictor;
+
+/** 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: string): string {
+  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: OxyAccountCacheEvictor,
+  accountId?: string,
+): void {
+  oxy.clearCacheEntry(OXY_ACCOUNT_LIST_CACHE_KEY);
+  oxy.clearCacheByPrefix(OXY_ACCOUNT_LIST_CACHE_QUERY_PREFIX);
+  if (accountId) {
+    oxy.clearCacheEntry(oxyAccountDetailCacheKey(accountId));
+  }
+}