@oxyhq/core 3.4.19 → 3.6.0

package/dist/types/index.d.ts

@@ -33,6 +33,7 @@ export type { ServiceTokenResponse } from './mixins/OxyServices.auth';
 export type { ServiceApp, ServiceActingAsVerification } from './mixins/OxyServices.utility';
 export type { CreateManagedAccountInput, ManagedAccountManager, ManagedAccount, } from './mixins/OxyServices.managedAccounts';
 export type { ContactDiscoveryMatch, ContactDiscoveryResponse, } from './mixins/OxyServices.contacts';
+export type { BulkFollowEntry, BulkFollowResult, BulkUnfollowEntry, BulkUnfollowResult, } from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 export { getNormalizedUserId, normalizeUserIdentity, normalizeUserIdentityOrNull, } from './utils/userIdentity';
 export { getCanonicalUserHandle, getNormalizedUserHandle, } from './utils/userHandle';

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

@@ -5,6 +5,38 @@ import type { User, Notification, NotificationPreferences, UserPreferences, Sear
 import type { UserNameResponse, UserProfileUpdate } from '@oxyhq/contracts';
 import type { OxyServicesBase } from '../OxyServices.base';
 import { type PaginationParams } from '../utils/apiUtils';
+/** Per-user outcome returned by `POST /users/follow/bulk`. */
+export interface BulkFollowEntry {
+    /** The user ID that was processed. */
+    userId: string;
+    /** Whether the follow was applied (or already in place) without error. */
+    success: boolean;
+    /** Whether the caller was already following this user before the request. */
+    alreadyFollowing: boolean;
+}
+/** Response shape of `POST /users/follow/bulk`. */
+export interface BulkFollowResult {
+    /** Per-user outcomes, in request order. */
+    results: BulkFollowEntry[];
+    /** Number of users newly followed by this request. */
+    followedCount: number;
+}
+/** Per-user outcome returned by `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowEntry {
+    /** The user ID that was processed. */
+    userId: string;
+    /** Whether the unfollow was applied (or already absent) without error. */
+    success: boolean;
+    /** Whether the caller was following this user before the request. */
+    wasFollowing: boolean;
+}
+/** Response shape of `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowResult {
+    /** Per-user outcomes, in request order. */
+    results: BulkUnfollowEntry[];
+    /** Number of users newly unfollowed by this request. */
+    unfollowedCount: number;
+}
 export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -161,12 +193,37 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             message: string;
         }>;
         /**
-         * Follow a user
+         * Follow a user.
+         *
+         * Invalidates the cached `GET /users/<id>/follow-status` response after
+         * the write. `getFollowStatus` caches for ~1 minute (identity-scoped);
+         * without busting that entry, a `FollowButton` that remounts within the
+         * TTL window re-reads the STALE pre-write status and reverts the optimistic
+         * UI (the "follow resets after navigating away and back" bug).
+         * `clearCacheEntry` deletes every identity-scoped variant of the key.
          */
         followUser(userId: string): Promise<{
             success: boolean;
             message: string;
         }>;
+        /**
+         * Follow multiple users in a single request.
+         *
+         * POSTs `/users/follow/bulk` with `{ userIds }` (server caps the batch at
+         * 200). Returns the per-user outcomes and the count of users newly
+         * followed. An empty `userIds` array resolves immediately with an empty
+         * result and performs no network call.
+         */
+        followUsers(userIds: string[]): Promise<BulkFollowResult>;
+        /**
+         * Unfollow multiple users in a single request.
+         *
+         * POSTs `/users/unfollow/bulk` with `{ userIds }` (server caps the batch at
+         * 200). Returns the per-user outcomes and the count of users newly
+         * unfollowed. An empty `userIds` array resolves immediately with an empty
+         * result and performs no network call.
+         */
+        unfollowUsers(userIds: string[]): Promise<BulkUnfollowResult>;
         /**
          * Unfollow a user
          */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.19",
+  "version": "3.6.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/index.ts

@@ -61,6 +61,12 @@ export type {
     ContactDiscoveryMatch,
     ContactDiscoveryResponse,
 } from './mixins/OxyServices.contacts';
+export type {
+    BulkFollowEntry,
+    BulkFollowResult,
+    BulkUnfollowEntry,
+    BulkUnfollowResult,
+} from './mixins/OxyServices.user';
 export { OxyAppDataIdentifierError } from './mixins/OxyServices.appData';
 
 // ---------------------------------------------------------------------------

package/src/mixins/OxyServices.user.ts

@@ -17,6 +17,42 @@ import { KeyManager } from '../crypto/keyManager';
 import { SignatureService } from '../crypto/signatureService';
 import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/userIdentity';
 
+/** Per-user outcome returned by `POST /users/follow/bulk`. */
+export interface BulkFollowEntry {
+  /** The user ID that was processed. */
+  userId: string;
+  /** Whether the follow was applied (or already in place) without error. */
+  success: boolean;
+  /** Whether the caller was already following this user before the request. */
+  alreadyFollowing: boolean;
+}
+
+/** Response shape of `POST /users/follow/bulk`. */
+export interface BulkFollowResult {
+  /** Per-user outcomes, in request order. */
+  results: BulkFollowEntry[];
+  /** Number of users newly followed by this request. */
+  followedCount: number;
+}
+
+/** Per-user outcome returned by `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowEntry {
+  /** The user ID that was processed. */
+  userId: string;
+  /** Whether the unfollow was applied (or already absent) without error. */
+  success: boolean;
+  /** Whether the caller was following this user before the request. */
+  wasFollowing: boolean;
+}
+
+/** Response shape of `POST /users/unfollow/bulk`. */
+export interface BulkUnfollowResult {
+  /** Per-user outcomes, in request order. */
+  results: BulkUnfollowEntry[];
+  /** Number of users newly unfollowed by this request. */
+  unfollowedCount: number;
+}
+
 export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -394,11 +430,68 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
 
 
     /**
-     * Follow a user
+     * Follow a user.
+     *
+     * Invalidates the cached `GET /users/<id>/follow-status` response after
+     * the write. `getFollowStatus` caches for ~1 minute (identity-scoped);
+     * without busting that entry, a `FollowButton` that remounts within the
+     * TTL window re-reads the STALE pre-write status and reverts the optimistic
+     * UI (the "follow resets after navigating away and back" bug).
+     * `clearCacheEntry` deletes every identity-scoped variant of the key.
      */
     async followUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<{ success: boolean; message: string }>('POST', `/users/${userId}/follow`, undefined, { cache: false });
+        this.clearCacheEntry(`GET:/users/${userId}/follow-status`);
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Follow multiple users in a single request.
+     *
+     * POSTs `/users/follow/bulk` with `{ userIds }` (server caps the batch at
+     * 200). Returns the per-user outcomes and the count of users newly
+     * followed. An empty `userIds` array resolves immediately with an empty
+     * result and performs no network call.
+     */
+    async followUsers(userIds: string[]): Promise<BulkFollowResult> {
+      if (userIds.length === 0) {
+        return { results: [], followedCount: 0 };
+      }
+      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`);
+        }
+        return result;
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
+    /**
+     * Unfollow multiple users in a single request.
+     *
+     * POSTs `/users/unfollow/bulk` with `{ userIds }` (server caps the batch at
+     * 200). Returns the per-user outcomes and the count of users newly
+     * unfollowed. An empty `userIds` array resolves immediately with an empty
+     * result and performs no network call.
+     */
+    async unfollowUsers(userIds: string[]): Promise<BulkUnfollowResult> {
+      if (userIds.length === 0) {
+        return { results: [], unfollowedCount: 0 };
+      }
+      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`);
+        }
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -409,7 +502,10 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      */
     async unfollowUser(userId: string): Promise<{ success: boolean; message: string }> {
       try {
-        return await this.makeRequest('DELETE', `/users/${userId}/follow`, undefined, { cache: false });
+        const result = await this.makeRequest<{ success: boolean; message: string }>('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`);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }

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

@@ -0,0 +1,168 @@
+/**
+ * Follow-status cache invalidation tests.
+ *
+ * Regression coverage for the "follow resets after navigating away and back"
+ * bug. `getFollowStatus(userId)` caches `GET /users/<id>/follow-status` for
+ * ~1 minute (identity-scoped). A follow/unfollow write must INVALIDATE that
+ * cached entry, otherwise a `FollowButton` that remounts within the TTL window
+ * re-reads the STALE pre-write status and reverts the optimistic UI.
+ *
+ * These tests pin down that:
+ *  - a cached `follow-status` is NOT served after `followUser` /
+ *    `unfollowUser` / `followUsers` / `unfollowUsers` — the next read
+ *    re-fetches and observes the new server truth,
+ *  - each mutation invalidates the exact logical key(s) for the affected ids.
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/**
+ * Build a non-verified JWT whose payload decodes to the given claims.
+ * `jwtDecode` only base64url-decodes the middle segment (no signature check).
+ */
+function makeJwt(payload: Record<string, unknown>): string {
+  const b64url = (obj: Record<string, unknown>): string =>
+    Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const fullPayload = { exp: Math.floor(Date.now() / 1000) + 3600, ...payload };
+  return `${b64url({ alg: 'none', typ: 'JWT' })}.${b64url(fullPayload)}.sig`;
+}
+
+/** A JSON `Response` mimicking the API's `{ data: ... }` success envelope. */
+function jsonResponse(data: unknown): Response {
+  return new Response(JSON.stringify({ data }), {
+    status: 200,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+describe('follow-status cache invalidation', () => {
+  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' });
+    oxy.httpService.setTokens(makeJwt({ userId: 'me' }));
+  });
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.clearAllMocks();
+  });
+
+  it('does NOT serve a stale cached follow-status after followUser', async () => {
+    // 1) Warm the cache: not following yet.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    const before = await oxy.getFollowStatus('target-1');
+    expect(before.isFollowing).toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read within the TTL is a cache hit (no extra network call).
+    await oxy.getFollowStatus('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Follow — write succeeds and must bust the cached follow-status.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+    await oxy.followUser('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Remount-style re-read MUST re-fetch and observe the fresh truth.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    const after = await oxy.getFollowStatus('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after.isFollowing).toBe(true);
+  });
+
+  it('does NOT serve a stale cached follow-status after unfollowUser', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    const before = await oxy.getFollowStatus('target-2');
+    expect(before.isFollowing).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+    await oxy.unfollowUser('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    const after = await oxy.getFollowStatus('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after.isFollowing).toBe(false);
+  });
+
+  it('busts cached follow-status for every id after followUsers (bulk)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    await oxy.getFollowStatus('a');
+    await oxy.getFollowStatus('b');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: [
+          { userId: 'a', success: true, alreadyFollowing: false },
+          { userId: 'b', success: true, alreadyFollowing: false },
+        ],
+        followedCount: 2,
+      }),
+    );
+    await oxy.followUsers(['a', 'b']);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    // Both ids must re-fetch.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    expect((await oxy.getFollowStatus('a')).isFollowing).toBe(true);
+    expect((await oxy.getFollowStatus('b')).isFollowing).toBe(true);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('busts cached follow-status for every id after unfollowUsers (bulk)', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: true }));
+    await oxy.getFollowStatus('a');
+    await oxy.getFollowStatus('b');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(
+      jsonResponse({
+        results: [
+          { userId: 'a', success: true, wasFollowing: true },
+          { userId: 'b', success: true, wasFollowing: true },
+        ],
+        unfollowedCount: 2,
+      }),
+    );
+    await oxy.unfollowUsers(['a', 'b']);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isFollowing: false }));
+    expect((await oxy.getFollowStatus('a')).isFollowing).toBe(false);
+    expect((await oxy.getFollowStatus('b')).isFollowing).toBe(false);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('invalidates the exact logical follow-status key on a single follow', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+    fetchMock.mockResolvedValueOnce(jsonResponse({ success: true, message: 'ok' }));
+
+    await oxy.followUser('target-3');
+
+    expect(clearSpy).toHaveBeenCalledWith('GET:/users/target-3/follow-status');
+    clearSpy.mockRestore();
+  });
+
+  it('does not invalidate or call the network when bulk follow gets an empty list', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+
+    const result = await oxy.followUsers([]);
+
+    expect(result).toEqual({ results: [], followedCount: 0 });
+    expect(fetchMock).not.toHaveBeenCalled();
+    expect(clearSpy).not.toHaveBeenCalled();
+    clearSpy.mockRestore();
+  });
+});