@oxyhq/core 13.0.0 → 14.0.0

package/dist/types/index.d.ts

@@ -80,8 +80,8 @@ export { HttpStatus, getErrorStatus, getErrorMessage, isAlreadyRegisteredError,
 export { DEFAULT_CIRCUIT_BREAKER_CONFIG, createCircuitBreakerState, calculateBackoffInterval, recordFailure, recordSuccess, shouldAllowRequest, delay, withRetry, } from './shared/utils/networkUtils';
 export type { CircuitBreakerState, CircuitBreakerConfig } from './shared/utils/networkUtils';
 export { translate } from './i18n';
-export { buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
-export type { PaginationParams, ApiResponse, ErrorResponse, } from './utils/apiUtils';
+export { buildQueryParams, buildSearchParams, buildUrl, buildPaginationParams, safeJsonParse, } from './utils/apiUtils';
+export type { PaginationParams, FollowGraphParams, FollowGraphSort, ApiResponse, ErrorResponse, } from './utils/apiUtils';
 export { ErrorCodes, createApiError, handleHttpError, validateRequiredFields, } from './utils/errorUtils';
 export { retryAsync } from './utils/asyncUtils';
 export { EMAIL_REGEX, USERNAME_REGEX, PASSWORD_REGEX, isValidEmail, isValidUsername, isValidPassword, isValidDisplayName, DISPLAY_NAME_ALLOWED_SCRIPTS, DISPLAY_NAME_DISALLOWED_SOURCE, DISPLAY_NAME_ORPHANED_MARK_SOURCE, isRequiredString, isRequiredNumber, isRequiredBoolean, isValidArray, isValidObject, isValidUUID, isValidURL, isValidDate, isValidFileSize, isValidFileType, sanitizeString, sanitizeHTML, isValidObjectId, validateAndSanitizeUserInput, } from './utils/validationUtils';

package/dist/types/mixins/OxyServices.user.d.ts

@@ -4,7 +4,7 @@
 import type { User, Notification, NotificationPreferences, UserPreferences, SearchProfilesResponse, PrivacySettings } from '../models/interfaces';
 import type { UserNameResponse, UserProfileUpdate, RecommendationRequest, RecommendationItem, ThemePreference } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { type PaginationParams } from '../utils/apiUtils';
+import { type PaginationParams, type FollowGraphParams } from '../utils/apiUtils';
 /**
  * Response of the single follow/unfollow toggle route
  * (`POST /users/:id/follow` and `DELETE /users/:id/follow`). The route reports a
@@ -329,6 +329,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         deleteAccount(confirmText: string): Promise<{
             message: string;
         }>;
+        /**
+         * Invalidate every cached read a follow/unfollow write invalidates.
+         *
+         * Shared by the four mutation entry points (`followUser`, `unfollowUser`,
+         * `followUsers`, `unfollowUsers`) so they can never drift on which caches a
+         * write busts.
+         *
+         * The follower/following/mutuals LISTS are cleared by PREFIX rather than by
+         * exact key. Those reads are paginated and ordered, so one logical list is
+         * spread across many content-addressed keys
+         * (`GET:/users/<id>/followers:{"limit":"20","offset":"40","sort":"oldest"}`);
+         * an exact-key clear would only bust whichever page/sort variant happened to
+         * be read last and would leave every other page stale. `clearCacheByPrefix`
+         * deletes all of them, and all identity-scoped variants of each.
+         */
+        invalidateFollowGraphCaches(targetUserIds: string[]): void;
         /**
          * Follow a user.
          *
@@ -386,17 +402,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getFollowStatuses(userIds: string[]): Promise<Record<string, boolean>>;
         /**
-         * Get user followers
+         * Get user followers.
+         *
+         * `sort` orders the underlying follow edges — `recent` (newest first, the
+         * server default) or `oldest`. Because the response is cached and the cache
+         * key is content-addressed on the query params, each `limit`/`offset`/`sort`
+         * combination is its own entry.
          */
-        getUserFollowers(userId: string, pagination?: PaginationParams): Promise<{
+        getUserFollowers(userId: string, pagination?: FollowGraphParams): Promise<{
             followers: User[];
             total: number;
             hasMore: boolean;
         }>;
         /**
-         * Get user following
+         * Get user following. `sort` behaves as in {@link getUserFollowers}.
          */
-        getUserFollowing(userId: string, pagination?: PaginationParams): Promise<{
+        getUserFollowing(userId: string, pagination?: FollowGraphParams): Promise<{
             following: User[];
             total: number;
             hasMore: boolean;
@@ -405,7 +426,7 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * Get user mutuals ("followers you know" — users the authenticated viewer
          * follows who also follow `userId`). The viewer is derived server-side from auth.
          */
-        getUserMutuals(userId: string, pagination?: PaginationParams): Promise<{
+        getUserMutuals(userId: string, pagination?: FollowGraphParams): Promise<{
             mutuals: User[];
             total: number;
             hasMore: boolean;

package/dist/types/server/index.d.ts

@@ -22,6 +22,8 @@ export { assertSafePublicUrl, isBlockedIp, safeFetch, SsrfRejection, UpstreamErr
 export type { SafeFetchOptions, SafeFetchResult, SsrfCheckFail, SsrfCheckOk, SsrfCheckResult, } from './safeFetch';
 export { createOxyCors } from './cors';
 export type { OxyCorsOptions } from './cors';
+export { buildOxyCspDirectives, buildOxyPagesHeaders, createOxySecurityHeaders, formatOxyCspPolicy, OXY_CSP_BASELINE, } from './securityHeaders';
+export type { OxyCspDirective, OxyCspExtensions, OxyPagesHeadersOptions, OxySecurityHeadersOptions, } from './securityHeaders';
 export { verifySecret } from './verifySecret';
 export { registrableApex } from '../utils/registrableApex';
 export { isOfficialWebOrigin } from '../utils/officialOrigins';

package/dist/types/server/securityHeaders.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared security headers (Helmet + Content-Security-Policy) for Oxy backends.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * A CSP only governs an origin that serves DOCUMENTS; on a JSON API it governs
+ * no browsing context. The Oxy origins that serve HTML through Cloudflare have
+ * so far either hand-written their own policy or shipped none at all, and two
+ * bugs follow from that:
+ *
+ *  1. THE CLOUDFLARE INSIGHTS BEACON IS BLOCKED BY A HAND-WRITTEN POLICY.
+ *     Cloudflare injects `<script src="https://static.cloudflareinsights.com/
+ *     beacon.min.js/...">` into HTML it proxies. No application code loads it,
+ *     so it cannot be allowlisted from the app side any other way, and an
+ *     origin whose policy says `script-src 'self'` logs
+ *     `Loading the script 'https://static.cloudflareinsights.com/beacon.min.js'
+ *     violates the following Content Security Policy directive: "script-src
+ *     'self'"` and collects nothing. The beacon needs BOTH hosts, and they are
+ *     different halves of the same feature: `static.cloudflareinsights.com`
+ *     serves the script (`script-src`), `cloudflareinsights.com` receives the
+ *     measurements (`connect-src`). Allowing only the script leaves the beacon
+ *     loading but unable to report, which looks fixed and is not. Verified in
+ *     production 2026-07-29: `mention.earth` serves HTML behind Cloudflare with
+ *     the beacon injected and `script-src 'self'` — blocked; `oxy.so` had
+ *     already allowlisted the same two hosts in its own static `_headers`,
+ *     independently, which is the divergence this baseline exists to end.
+ *
+ *  2. AN EXPLICIT DIRECTIVE SILENTLY REPLACES HELMET'S DEFAULT.
+ *     Writing `scriptSrc: ['https://example.com']` drops `'self'` — the page's
+ *     own bundle stops loading (or, worse, only some lazily-loaded chunk does,
+ *     so it ships). This helper makes that structurally impossible: callers can
+ *     only ADD sources to the Oxy baseline, never replace a directive, and they
+ *     cannot pass their own `contentSecurityPolicy` through to Helmet at all
+ *     (the option is typed `never`).
+ *
+ * WHAT IT PROVIDES
+ * ----------------
+ * `createOxySecurityHeaders(options)` returns the Helmet middleware with the
+ * Oxy-wide CSP baseline applied, plus per-app extensions merged (and deduped)
+ * into it. Everything Helmet does that is NOT the CSP (HSTS, frameguard,
+ * referrer policy, CORP/COOP, …) is passed straight through, so an app keeps
+ * full control of those.
+ *
+ * `buildOxyCspDirectives(extensions)` is the same resolution as a pure
+ * function, for the Oxy document origins that are NOT Express — a Next.js
+ * `headers()`, a Cloudflare Pages `_headers` generator — so one policy can
+ * cover them without a second implementation.
+ *
+ * SCOPE: mount this on backends that serve HTML. A JSON-only API gains nothing
+ * from a source-list CSP; harden those with the non-CSP headers instead
+ * (`hsts`, `noSniff`, `frameguard`, CORP) rather than adding directives that
+ * apply to no document.
+ *
+ * Node/Express-only: exported solely from `@oxyhq/core/server`.
+ */
+import type { RequestHandler } from 'express';
+import { type HelmetOptions } from 'helmet';
+/** The CSP directives an Oxy app may extend, in Helmet's camelCase spelling. */
+export type OxyCspDirective = 'baseUri' | 'connectSrc' | 'defaultSrc' | 'fontSrc' | 'formAction' | 'frameAncestors' | 'frameSrc' | 'imgSrc' | 'manifestSrc' | 'mediaSrc' | 'objectSrc' | 'scriptSrc' | 'scriptSrcAttr' | 'scriptSrcElem' | 'styleSrc' | 'styleSrcElem' | 'workerSrc';
+/**
+ * Per-app ADDITIONS to the Oxy baseline, keyed by directive. Values are merged
+ * into the baseline and deduped — they never replace it, so `'self'` (and the
+ * Cloudflare beacon hosts) cannot be lost. Extending a directive the baseline
+ * does not define seeds it with `'self'` first, for the same reason.
+ */
+export type OxyCspExtensions = Partial<Record<OxyCspDirective, readonly string[]>>;
+/**
+ * The Oxy-wide CSP baseline. Deliberately the floor every Oxy origin needs, not
+ * a superset of what any one app allows — permissive sources an individual app
+ * wants (`https:` images, `blob:` media, embed hosts, LiveKit) are that app's
+ * extension, so each widening stays visible at its call site.
+ *
+ * `style-src` carries `'unsafe-inline'` because react-native-web injects its
+ * stylesheet as inline `<style>` at runtime; without it every Oxy web app
+ * renders unstyled.
+ */
+export declare const OXY_CSP_BASELINE: Readonly<Partial<Record<OxyCspDirective, readonly string[]>>>;
+/**
+ * Resolve the effective CSP directives: the Oxy baseline, with each app
+ * extension merged in and deduped.
+ *
+ * Merge rules:
+ *  - A baseline directive is EXTENDED, never replaced — `'self'` and the
+ *    Cloudflare beacon hosts always survive.
+ *  - A directive absent from the baseline is seeded with `'self'`, so adding
+ *    (say) an embed host to `frame-src` cannot lock the origin out of itself.
+ *  - A directive whose baseline is exactly `'none'` is CLOSED: extending it
+ *    drops the sentinel, because `'none'` alongside any other source is
+ *    meaningless per the CSP spec. This is how an app that must be framable
+ *    opts back in with `frameAncestors: ["'self'"]`.
+ *
+ * @example
+ * ```ts
+ * buildOxyCspDirectives({ frameSrc: ['https://player.vimeo.com'] });
+ * // → { ..., 'frame-src': ["'self'", 'https://player.vimeo.com'], ... }
+ * ```
+ */
+export declare function buildOxyCspDirectives(extensions?: OxyCspExtensions): Record<string, string[]>;
+/**
+ * Serialize resolved CSP directives into the single-line header value browsers
+ * and Cloudflare `_headers` expect. Valueless directives (e.g.
+ * `upgrade-insecure-requests`) emit the name alone.
+ */
+export declare function formatOxyCspPolicy(directives: Record<string, string[]>): string;
+export interface OxyPagesHeadersOptions {
+    /** Per-app additions merged into {@link OXY_CSP_BASELINE}. */
+    csp?: OxyCspExtensions;
+    /**
+     * Emit `Strict-Transport-Security` (default `true`). Cloudflare Pages serves
+     * HTTPS only, so static deploys should keep this on.
+     */
+    hsts?: boolean;
+}
+/**
+ * Build a Cloudflare Pages `_headers` block for an Oxy HTML origin. Uses the
+ * same CSP resolution as {@link createOxySecurityHeaders} plus the non-CSP
+ * hardening headers Helmet would add on an Express HTML backend.
+ */
+export declare function buildOxyPagesHeaders(options?: OxyPagesHeadersOptions): string;
+export interface OxySecurityHeadersOptions {
+    /**
+     * Per-app additions to the Oxy CSP baseline. Merged, deduped, never
+     * replacing — see {@link buildOxyCspDirectives}.
+     */
+    csp?: OxyCspExtensions;
+    /**
+     * Everything Helmet does that is not the CSP: `hsts`, `frameguard`,
+     * `referrerPolicy`, `crossOriginResourcePolicy`, … Passed straight through.
+     *
+     * `contentSecurityPolicy` is typed `never` on purpose: the CSP is owned by
+     * this helper so the baseline cannot be replaced (nor the `'self'` guarantee
+     * bypassed) by an app that hands Helmet its own directive block. Extend it
+     * through `csp` instead.
+     */
+    helmet?: HelmetOptions & {
+        contentSecurityPolicy?: never;
+    };
+}
+/**
+ * Build the shared Oxy security-headers middleware: Helmet with the Oxy CSP
+ * baseline plus this app's extensions.
+ *
+ * @example
+ * ```ts
+ * app.use(createOxySecurityHeaders({
+ *   csp: {
+ *     connectSrc: ['https://api.example.com', 'wss://api.example.com'],
+ *     frameSrc: ['https://player.vimeo.com'],
+ *   },
+ *   helmet: { crossOriginResourcePolicy: { policy: 'cross-origin' } },
+ * }));
+ * ```
+ */
+export declare function createOxySecurityHeaders(options?: OxySecurityHeadersOptions): RequestHandler;

package/dist/types/utils/apiUtils.d.ts

@@ -2,18 +2,39 @@
  * Utility functions for common API patterns
  */
 /**
- * Build URL search parameters from an object
+ * Build a plain query-parameter record from an object, stringifying values and
+ * dropping `undefined`/`null` entries.
+ *
+ * This is the shape `OxyServices.makeRequest` expects for a GET's `params`:
+ * `HttpService` inspects it with `Object.keys(...)` (both to decide whether to
+ * append a query string and to build the request's cache key), and
+ * `Object.keys(new URLSearchParams({ limit: '20' }))` is `[]` — a
+ * `URLSearchParams` exposes its entries through iterator methods, never as own
+ * enumerable properties. Passing one to `makeRequest` therefore silently drops
+ * the whole query string. Always hand `makeRequest` a plain record.
+ *
+ * Generic over the input object rather than taking `Record<string, unknown>`,
+ * because a TypeScript `interface` (`PaginationParams`, `FollowGraphParams`, …)
+ * has no implicit index signature and so is not assignable to that type.
+ */
+export declare function buildQueryParams<T extends object>(params: T): Record<string, string>;
+/**
+ * Build URL search parameters from an object.
+ *
+ * For building a URL string only — see {@link buildQueryParams} for the shape
+ * `makeRequest` needs.
+ *
  * @param params Object with parameter key-value pairs
  * @returns URLSearchParams instance
  */
-export declare function buildSearchParams(params: Record<string, any>): URLSearchParams;
+export declare function buildSearchParams<T extends object>(params: T): URLSearchParams;
 /**
  * Build URL with search parameters
  * @param baseUrl Base URL
  * @param params Object with parameter key-value pairs
  * @returns Complete URL with search parameters
  */
-export declare function buildUrl(baseUrl: string, params?: Record<string, any>): string;
+export declare function buildUrl<T extends object>(baseUrl: string, params?: T): string;
 /**
  * Common pagination parameters
  */
@@ -22,11 +43,32 @@ export interface PaginationParams {
     offset?: number;
 }
 /**
- * Build pagination search parameters
+ * Ordering for the follow-graph list endpoints (`/users/:id/followers`,
+ * `/users/:id/following`, `/users/:id/mutuals`).
+ *
+ * - `recent` — newest follow edge first (the server default).
+ * - `oldest` — oldest follow edge first.
+ */
+export type FollowGraphSort = 'recent' | 'oldest';
+/**
+ * Pagination plus the follow-graph ordering.
+ *
+ * Kept separate from {@link PaginationParams}, which is shared by endpoints
+ * that have no `sort` at all.
+ */
+export interface FollowGraphParams extends PaginationParams {
+    sort?: FollowGraphSort;
+}
+/**
+ * Build pagination query parameters.
+ *
+ * Returns a plain record — NOT a `URLSearchParams` — because that is the only
+ * shape `makeRequest`/`HttpService` can read. See {@link buildQueryParams}.
+ *
  * @param params Pagination parameters
- * @returns URLSearchParams with pagination
+ * @returns Query record with pagination
  */
-export declare function buildPaginationParams(params: PaginationParams): URLSearchParams;
+export declare function buildPaginationParams(params: PaginationParams): Record<string, string>;
 /**
  * Common API response wrapper
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "13.0.0",
+  "version": "14.0.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -131,7 +131,8 @@
     "expo-crypto": "*",
     "expo-secure-store": "*",
     "express": "^4.0.0",
-    "express-rate-limit": "^7.0.0"
+    "express-rate-limit": "^7.0.0",
+    "helmet": "^8.0.0"
   },
   "peerDependenciesMeta": {
     "@react-native-async-storage/async-storage": {
@@ -145,6 +146,9 @@
     },
     "express": {
       "optional": true
+    },
+    "helmet": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -160,6 +164,7 @@
     "express-rate-limit": "^8.6.0",
     "regexpu-core": "^6.4.0",
     "release-it": "^19.0.6",
-    "typescript": "^5.9.2"
+    "typescript": "^5.9.2",
+    "helmet": "^8.3.0"
   }
 }

package/src/index.ts

@@ -468,6 +468,7 @@ export { translate } from './i18n';
 // API request / URL helpers
 // ---------------------------------------------------------------------------
 export {
+    buildQueryParams,
     buildSearchParams,
     buildUrl,
     buildPaginationParams,
@@ -475,6 +476,8 @@ export {
 } from './utils/apiUtils';
 export type {
     PaginationParams,
+    FollowGraphParams,
+    FollowGraphSort,
     ApiResponse,
     ErrorResponse,
 } from './utils/apiUtils';

package/src/mixins/OxyServices.user.ts

@@ -19,7 +19,12 @@ import type {
 } from '@oxyhq/contracts';
 import { recommendationRequestSchema } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
-import { buildSearchParams, buildPaginationParams, type PaginationParams } from '../utils/apiUtils';
+import {
+  buildQueryParams,
+  buildPaginationParams,
+  type PaginationParams,
+  type FollowGraphParams,
+} from '../utils/apiUtils';
 import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
@@ -198,14 +203,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async searchProfiles(query: string, pagination?: PaginationParams): Promise<SearchProfilesResponse> {
       try {
-        const params = { query, ...pagination };
-        const searchParams = buildSearchParams(params);
-        const paramsObj = Object.fromEntries(searchParams.entries());
-
         const response = await this.makeRequest<SearchProfilesResponse>(
           'GET',
           '/profiles/search',
-          paramsObj,
+          buildQueryParams({ query, ...pagination }),
           {
             cache: true,
             cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -727,6 +728,42 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
 
+    /**
+     * Invalidate every cached read a follow/unfollow write invalidates.
+     *
+     * Shared by the four mutation entry points (`followUser`, `unfollowUser`,
+     * `followUsers`, `unfollowUsers`) so they can never drift on which caches a
+     * write busts.
+     *
+     * The follower/following/mutuals LISTS are cleared by PREFIX rather than by
+     * exact key. Those reads are paginated and ordered, so one logical list is
+     * spread across many content-addressed keys
+     * (`GET:/users/<id>/followers:{"limit":"20","offset":"40","sort":"oldest"}`);
+     * an exact-key clear would only bust whichever page/sort variant happened to
+     * be read last and would leave every other page stale. `clearCacheByPrefix`
+     * deletes all of them, and all identity-scoped variants of each.
+     */
+    invalidateFollowGraphCaches(targetUserIds: string[]): void {
+      for (const id of targetUserIds) {
+        this.clearCacheEntry(`GET:/users/${id}/follow-status`);
+        // Profile fetches embed viewer-relative `relationship` — bust so a
+        // remount doesn't serve a stale isFollowing for up to 5 minutes.
+        this.clearCacheEntry(`GET:/users/${id}`);
+        // The target gained/lost a follower, and the viewer's presence in the
+        // target's "followers you know" set changed with it.
+        this.clearCacheByPrefix(`GET:/users/${id}/followers`);
+        this.clearCacheByPrefix(`GET:/users/${id}/mutuals`);
+      }
+      this.clearCacheByPrefix('GET:/profiles/username/');
+      this.clearCacheByPrefix('GET:/profiles/resolve');
+      // The write changed the viewer's OWN following list and graph.
+      const viewerId = this.getCurrentUserId();
+      if (viewerId) {
+        this.clearCacheByPrefix(`GET:/users/${viewerId}/following`);
+      }
+      this.clearCacheEntry('GET:/users/me/graph');
+    }
+
     /**
      * Follow a user.
      *
@@ -740,16 +777,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     async followUser(userId: string): Promise<FollowMutationResult> {
       try {
         const result = await this.makeRequest<FollowMutationResult>('POST', `/users/${userId}/follow`, undefined, { cache: false });
-        this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
-        // Profile fetches embed viewer-relative `relationship` — bust so a
-        // remount doesn't serve a stale isFollowing for up to 5 minutes.
-        this.clearCacheEntry(`GET:/users/${userId}`);
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheByPrefix('GET:/profiles/resolve');
-        // The follow changed the viewer's graph — bust the cached consolidated
-        // `GET /users/me/graph` so the next read reflects the new following/
-        // mutual set instead of the stale pre-write snapshot.
-        this.clearCacheEntry('GET:/users/me/graph');
+        this.invalidateFollowGraphCaches([userId]);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -770,15 +798,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
       try {
         const result = await this.makeRequest<BulkFollowResult>('POST', '/users/follow/bulk', { userIds }, { cache: false });
-        // Bust each affected user's cached follow-status (see `followUser`).
-        for (const id of userIds) {
-          this.clearCacheEntry(`GET:/users/${id}/follow-status`);
-          this.clearCacheEntry(`GET:/users/${id}`);
-        }
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheByPrefix('GET:/profiles/resolve');
-        // The batch changed the viewer's graph — bust the consolidated cache.
-        this.clearCacheEntry('GET:/users/me/graph');
+        this.invalidateFollowGraphCaches(userIds);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -799,15 +819,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
       try {
         const result = await this.makeRequest<BulkUnfollowResult>('POST', '/users/unfollow/bulk', { userIds }, { cache: false });
-        // Bust each affected user's cached follow-status (see `followUser`).
-        for (const id of userIds) {
-          this.clearCacheEntry(`GET:/users/${id}/follow-status`);
-          this.clearCacheEntry(`GET:/users/${id}`);
-        }
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheByPrefix('GET:/profiles/resolve');
-        // The batch changed the viewer's graph — bust the consolidated cache.
-        this.clearCacheEntry('GET:/users/me/graph');
+        this.invalidateFollowGraphCaches(userIds);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -820,13 +832,7 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     async unfollowUser(userId: string): Promise<FollowMutationResult> {
       try {
         const result = await this.makeRequest<FollowMutationResult>('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
-        // Bust the cached follow-status so a remount reads fresh truth (see `followUser`).
-        this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
-        this.clearCacheEntry(`GET:/users/${userId}`);
-        this.clearCacheByPrefix('GET:/profiles/username/');
-        this.clearCacheByPrefix('GET:/profiles/resolve');
-        // The unfollow changed the viewer's graph — bust the consolidated cache.
-        this.clearCacheEntry('GET:/users/me/graph');
+        this.invalidateFollowGraphCaches([userId]);
         return result;
       } catch (error) {
         throw this.handleError(error);
@@ -899,14 +905,19 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get user followers
+     * Get user followers.
+     *
+     * `sort` orders the underlying follow edges — `recent` (newest first, the
+     * server default) or `oldest`. Because the response is cached and the cache
+     * key is content-addressed on the query params, each `limit`/`offset`/`sort`
+     * combination is its own entry.
      */
     async getUserFollowers(
       userId: string,
-      pagination?: PaginationParams
+      pagination?: FollowGraphParams
     ): Promise<{ followers: User[]; total: number; hasMore: boolean }> {
       try {
-        const params = buildPaginationParams(pagination || {});
+        const params = buildQueryParams(pagination || {});
         const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/users/${userId}/followers`, params, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -922,14 +933,14 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get user following
+     * Get user following. `sort` behaves as in {@link getUserFollowers}.
      */
     async getUserFollowing(
       userId: string,
-      pagination?: PaginationParams
+      pagination?: FollowGraphParams
     ): Promise<{ following: User[]; total: number; hasMore: boolean }> {
       try {
-        const params = buildPaginationParams(pagination || {});
+        const params = buildQueryParams(pagination || {});
         const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/users/${userId}/following`, params, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache
@@ -950,10 +961,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async getUserMutuals(
       userId: string,
-      pagination?: PaginationParams
+      pagination?: FollowGraphParams
     ): Promise<{ mutuals: User[]; total: number; hasMore: boolean }> {
       try {
-        const params = buildPaginationParams(pagination || {});
+        const params = buildQueryParams(pagination || {});
         const response = await this.makeRequest<{ data: User[]; pagination: { total: number; hasMore: boolean } }>('GET', `/users/${userId}/mutuals`, params, {
           cache: true,
           cacheTTL: 2 * 60 * 1000, // 2 minutes cache