@oxyhq/core 19.0.0 → 19.1.0

package/src/mixins/OxyServices.accounts.ts

@@ -38,6 +38,7 @@ 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';
 
 // ---------------------------------------------------------------------------
@@ -87,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;
@@ -98,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`
@@ -106,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;
@@ -264,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`. */
@@ -702,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);
@@ -793,8 +809,7 @@ 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;
@@ -826,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);
@@ -859,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[]> {
@@ -968,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);
@@ -1310,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);
     }
 
     /**
@@ -1351,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

@@ -29,6 +29,7 @@ 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';
 
@@ -540,10 +541,11 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * 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`). Without the sweep a follow-up
-     * `getUserBySession` inside the cache window returns the pre-update user —
-     * most visibly during onboarding, where the username step flickers back as
-     * if nothing was saved.
+     * `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.
      */
@@ -554,6 +556,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         );
 
         evictOxyIdentityCache(this, result?.id);
+        evictOxyAccountForestCache(this, result?.id);
 
         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?');
     });

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 });
+      }
+    });
+  });
+});