@oxyhq/core 3.8.1 → 3.8.2

package/src/mixins/OxyServices.features.ts

@@ -159,10 +159,14 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
          */
         async subscribe(planId: string, paymentMethodId?: string): Promise<SubscriptionResult> {
             return this.withAuthRetry(async () => {
-                return await this.makeRequest<SubscriptionResult>('POST', '/subscriptions/subscribe', {
+                const result = await this.makeRequest<SubscriptionResult>('POST', '/subscriptions/subscribe', {
                     planId,
                     paymentMethodId,
                 }, { cache: false });
+                // The current subscription changed — bust its cached read so
+                // `getCurrentSubscription()` reflects the new plan immediately.
+                this.clearCacheEntry('GET:/subscriptions/current');
+                return result;
             }, 'subscribe');
         }
 
@@ -171,10 +175,12 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
          */
         async subscribeToFeature(featureId: string, paymentMethodId?: string): Promise<SubscriptionResult> {
             return this.withAuthRetry(async () => {
-                return await this.makeRequest<SubscriptionResult>('POST', '/subscriptions/features/subscribe', {
+                const result = await this.makeRequest<SubscriptionResult>('POST', '/subscriptions/features/subscribe', {
                     featureId,
                     paymentMethodId,
                 }, { cache: false });
+                this.clearCacheEntry('GET:/subscriptions/current');
+                return result;
             }, 'subscribeToFeature');
         }
 
@@ -186,6 +192,7 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
                 await this.makeRequest('POST', `/subscriptions/${subscriptionId}/cancel`, undefined, {
                     cache: false,
                 });
+                this.clearCacheEntry('GET:/subscriptions/current');
             }, 'cancelSubscription');
         }
 
@@ -197,6 +204,7 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
                 await this.makeRequest('POST', `/subscriptions/${subscriptionId}/reactivate`, undefined, {
                     cache: false,
                 });
+                this.clearCacheEntry('GET:/subscriptions/current');
             }, 'reactivateSubscription');
         }
 
@@ -248,45 +256,65 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
         }
 
         /**
-         * Save an item
+         * Save an item.
+         *
+         * Busts the cached own saved-items list (`GET /saves`, ~short TTL) so a
+         * follow-up `getSavedItems()` observes the new item. The `userId`-scoped
+         * variant (`/users/<id>/saves`) is another user's list and is not
+         * affected by the caller's own save.
          */
         async saveItem(itemId: string, itemType: string, collectionId?: string): Promise<SavedItem> {
             return this.withAuthRetry(async () => {
-                return await this.makeRequest<SavedItem>('POST', '/saves', {
+                const result = await this.makeRequest<SavedItem>('POST', '/saves', {
                     itemId,
                     itemType,
                     collectionId,
                 }, { cache: false });
+                this.clearCacheEntry('GET:/saves');
+                return result;
             }, 'saveItem');
         }
 
         /**
-         * Remove an item from saves
+         * Remove an item from saves.
+         *
+         * Busts the cached own saved-items list so the removed item is gone on
+         * the next read (see `saveItem`).
          */
         async removeSavedItem(saveId: string): Promise<void> {
             return this.withAuthRetry(async () => {
                 await this.makeRequest('DELETE', `/saves/${saveId}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/saves');
             }, 'removeSavedItem');
         }
 
         /**
-         * Create a collection
+         * Create a collection.
+         *
+         * Busts the cached own collections list (`GET /collections`) so the new
+         * collection appears on the next read.
          */
         async createCollection(name: string, description?: string): Promise<Collection> {
             return this.withAuthRetry(async () => {
-                return await this.makeRequest<Collection>('POST', '/collections', {
+                const result = await this.makeRequest<Collection>('POST', '/collections', {
                     name,
                     description,
                 }, { cache: false });
+                this.clearCacheEntry('GET:/collections');
+                return result;
             }, 'createCollection');
         }
 
         /**
-         * Delete a collection
+         * Delete a collection.
+         *
+         * Busts the cached own collections list so the deleted collection is
+         * gone on the next read (see `createCollection`).
          */
         async deleteCollection(collectionId: string): Promise<void> {
             return this.withAuthRetry(async () => {
                 await this.makeRequest('DELETE', `/collections/${collectionId}`, undefined, { cache: false });
+                this.clearCacheEntry('GET:/collections');
             }, 'deleteCollection');
         }
 
@@ -330,20 +358,29 @@ export function OxyServicesFeaturesMixin<T extends typeof OxyServicesBase>(Base:
         }
 
         /**
-         * Clear user history
+         * Clear user history.
+         *
+         * `getUserHistory` caches per (limit, offset) page, so its cache key
+         * carries serialized params (`GET:/history` and `GET:/history:<params>`).
+         * A prefix sweep busts every cached page of the own history at once.
          */
         async clearUserHistory(): Promise<void> {
             return this.withAuthRetry(async () => {
                 await this.makeRequest('DELETE', '/history', undefined, { cache: false });
+                this.clearCacheByPrefix('GET:/history');
             }, 'clearUserHistory');
         }
 
         /**
-         * Delete a history item
+         * Delete a history item.
+         *
+         * Busts every cached page of the own history (see `clearUserHistory`)
+         * so the removed item no longer appears on the next read.
          */
         async deleteHistoryItem(itemId: string): Promise<void> {
             return this.withAuthRetry(async () => {
                 await this.makeRequest('DELETE', `/history/${itemId}`, undefined, { cache: false });
+                this.clearCacheByPrefix('GET:/history');
             }, 'deleteHistoryItem');
         }
 

package/src/mixins/OxyServices.managedAccounts.ts

@@ -41,13 +41,17 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
      * Create a new managed account (sub-account).
      *
      * The server creates a User document with `isManagedAccount: true` and links
-     * it to the authenticated user as owner.
+     * it to the authenticated user as owner. Invalidates the cached
+     * `GET /managed-accounts` list (~2-minute TTL, identity-scoped) so the next
+     * read includes the newly created account.
      */
     async createManagedAccount(data: CreateManagedAccountInput): Promise<ManagedAccount> {
       try {
-        return await this.makeRequest<ManagedAccount>('POST', '/managed-accounts', data, {
+        const result = await this.makeRequest<ManagedAccount>('POST', '/managed-accounts', data, {
           cache: false,
         });
+        this.clearCacheEntry('GET:/managed-accounts');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -84,12 +88,19 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
     /**
      * Update a managed account's profile data.
      * Requires owner or admin role.
+     *
+     * Invalidates both the cached detail (`GET /managed-accounts/<id>`) and the
+     * cached list (`GET /managed-accounts`, which embeds account profile data)
+     * so neither serves the pre-update snapshot within their ~2-minute TTL.
      */
     async updateManagedAccount(accountId: string, data: Partial<CreateManagedAccountInput>): Promise<ManagedAccount> {
       try {
-        return await this.makeRequest<ManagedAccount>('PUT', `/managed-accounts/${accountId}`, data, {
+        const result = await this.makeRequest<ManagedAccount>('PUT', `/managed-accounts/${accountId}`, data, {
           cache: false,
         });
+        this.clearCacheEntry(`GET:/managed-accounts/${accountId}`);
+        this.clearCacheEntry('GET:/managed-accounts');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -98,12 +109,17 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
     /**
      * Delete a managed account permanently.
      * Requires owner role.
+     *
+     * Invalidates the cached detail and list responses so the deleted account
+     * is not served from cache.
      */
     async deleteManagedAccount(accountId: string): Promise<void> {
       try {
         await this.makeRequest<void>('DELETE', `/managed-accounts/${accountId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry(`GET:/managed-accounts/${accountId}`);
+        this.clearCacheEntry('GET:/managed-accounts');
       } catch (error) {
         throw this.handleError(error);
       }
@@ -113,6 +129,9 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
      * Add a manager to a managed account.
      * Requires owner or admin role on the account.
      *
+     * Mutates the account's `managers[]`, which is returned by the detail and
+     * list reads — invalidate both so they re-fetch the updated manager set.
+     *
      * @param accountId - The managed account to add the manager to
      * @param userId - The user to grant management access
      * @param role - The role to assign: 'admin' or 'editor'
@@ -122,6 +141,8 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
         await this.makeRequest<void>('POST', `/managed-accounts/${accountId}/managers`, { userId, role }, {
           cache: false,
         });
+        this.clearCacheEntry(`GET:/managed-accounts/${accountId}`);
+        this.clearCacheEntry('GET:/managed-accounts');
       } catch (error) {
         throw this.handleError(error);
       }
@@ -131,6 +152,9 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
      * Remove a manager from a managed account.
      * Requires owner role.
      *
+     * Invalidates the detail and list responses so the updated `managers[]`
+     * is observed on the next read (see `addManager`).
+     *
      * @param accountId - The managed account
      * @param userId - The manager to remove
      */
@@ -139,6 +163,8 @@ export function OxyServicesManagedAccountsMixin<T extends typeof OxyServicesBase
         await this.makeRequest<void>('DELETE', `/managed-accounts/${accountId}/managers/${userId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry(`GET:/managed-accounts/${accountId}`);
+        this.clearCacheEntry('GET:/managed-accounts');
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.privacy.ts

@@ -63,7 +63,13 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * Block a user
+     * Block a user.
+     *
+     * Invalidates the cached `GET /privacy/blocked` response after the write.
+     * `getBlockedUsers` caches for ~1 minute (identity-scoped); without busting
+     * that entry, a consumer that re-reads the blocked list within the TTL
+     * window would not see the user it just blocked. `clearCacheEntry` deletes
+     * every identity-scoped variant of the key.
      * @param userId - The user ID to block
      * @returns Success message
      */
@@ -72,16 +78,21 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('POST', `/privacy/blocked/${userId}`, undefined, {
+        const result = await this.makeRequest<{ message: string }>('POST', `/privacy/blocked/${userId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry('GET:/privacy/blocked');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
     }
 
     /**
-     * Unblock a user
+     * Unblock a user.
+     *
+     * Busts the cached `GET /privacy/blocked` response so a remount reads the
+     * fresh list without the just-unblocked user (see `blockUser`).
      * @param userId - The user ID to unblock
      * @returns Success message
      */
@@ -90,9 +101,11 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('DELETE', `/privacy/blocked/${userId}`, undefined, {
+        const result = await this.makeRequest<{ message: string }>('DELETE', `/privacy/blocked/${userId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry('GET:/privacy/blocked');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -131,7 +144,13 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
     }
 
     /**
-     * Restrict a user (limit their interactions without fully blocking)
+     * Restrict a user (limit their interactions without fully blocking).
+     *
+     * Invalidates the cached `GET /privacy/restricted` response after the write.
+     * `getRestrictedUsers` caches for ~1 minute (identity-scoped); without
+     * busting that entry, a consumer that re-reads the restricted list within
+     * the TTL window would not see the user it just restricted.
+     * `clearCacheEntry` deletes every identity-scoped variant of the key.
      * @param userId - The user ID to restrict
      * @returns Success message
      */
@@ -140,16 +159,21 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('POST', `/privacy/restricted/${userId}`, undefined, {
+        const result = await this.makeRequest<{ message: string }>('POST', `/privacy/restricted/${userId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry('GET:/privacy/restricted');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
     }
 
     /**
-     * Unrestrict a user
+     * Unrestrict a user.
+     *
+     * Busts the cached `GET /privacy/restricted` response so a remount reads the
+     * fresh list without the just-unrestricted user (see `restrictUser`).
      * @param userId - The user ID to unrestrict
      * @returns Success message
      */
@@ -158,9 +182,11 @@ export function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase>(Base:
         if (!userId) {
           throw new Error('User ID is required');
         }
-        return await this.makeRequest<{ message: string }>('DELETE', `/privacy/restricted/${userId}`, undefined, {
+        const result = await this.makeRequest<{ message: string }>('DELETE', `/privacy/restricted/${userId}`, undefined, {
           cache: false,
         });
+        this.clearCacheEntry('GET:/privacy/restricted');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.topics.ts

@@ -124,9 +124,13 @@ export function OxyServicesTopicsMixin<T extends typeof OxyServicesBase>(Base: T
       }
     ): Promise<TopicData> {
       try {
-        return await this.makeRequest('PATCH', `/topics/${slug}`, data, {
+        const result = await this.makeRequest<TopicData>('PATCH', `/topics/${slug}`, data, {
           cache: false,
         });
+        // Bust the cached topic detail so `getTopicBySlug(slug)` reflects the
+        // updated metadata immediately (it caches at the LONG TTL).
+        this.clearCacheEntry(`GET:/topics/${slug}`);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.user.ts

@@ -482,16 +482,25 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Update privacy settings
+     * Update privacy settings.
+     *
+     * Invalidates the cached `GET /privacy/<id>/privacy` response (the exact
+     * key `getPrivacySettings` reads, scoped to the same `id`) after the write.
+     * `getPrivacySettings` caches for ~2 minutes (identity-scoped); without
+     * busting that entry, a follow-up read within the TTL window returns the
+     * pre-update settings. `clearCacheEntry` deletes every identity-scoped
+     * variant of the key.
      * @param settings - Partial privacy settings object
      * @param userId - The user ID (defaults to current user)
      */
     async updatePrivacySettings(settings: Partial<PrivacySettings>, userId?: string): Promise<PrivacySettings> {
       try {
         const id = userId || (await this.getCurrentUser()).id;
-        return await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
+        const result = await this.makeRequest<PrivacySettings>('PATCH', `/privacy/${id}/privacy`, settings, {
           cache: false,
         });
+        this.clearCacheEntry(`GET:/privacy/${id}/privacy`);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }

package/src/mixins/OxyServices.workspaces.ts

@@ -140,6 +140,9 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
           data,
           { cache: false },
         );
+        // Bust the cached workspace list so the new workspace appears on the
+        // next `getWorkspaces()` read within the TTL window.
+        this.clearCacheEntry('GET:/workspaces');
         return res.workspace;
       } catch (error) {
         throw this.handleError(error);
@@ -180,6 +183,9 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
           data,
           { cache: false },
         );
+        // Bust the cached detail and list — both surface workspace fields.
+        this.clearCacheEntry(`GET:/workspaces/${encodeURIComponent(workspaceId)}`);
+        this.clearCacheEntry('GET:/workspaces');
         return res.workspace;
       } catch (error) {
         throw this.handleError(error);
@@ -192,12 +198,17 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
      */
     async deleteWorkspace(workspaceId: string): Promise<WorkspaceSuccessResult> {
       try {
-        return await this.makeRequest<WorkspaceSuccessResult>(
+        const result = await this.makeRequest<WorkspaceSuccessResult>(
           'DELETE',
           `/workspaces/${encodeURIComponent(workspaceId)}`,
           undefined,
           { cache: false },
         );
+        // Bust every cached representation of the deleted workspace.
+        this.clearCacheEntry(`GET:/workspaces/${encodeURIComponent(workspaceId)}`);
+        this.clearCacheEntry(`GET:/workspaces/${encodeURIComponent(workspaceId)}/members`);
+        this.clearCacheEntry('GET:/workspaces');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -239,6 +250,7 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
           data,
           { cache: false },
         );
+        this._invalidateWorkspaceMembership(workspaceId);
         return res.member;
       } catch (error) {
         throw this.handleError(error);
@@ -263,6 +275,7 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
           data,
           { cache: false },
         );
+        this._invalidateWorkspaceMembership(workspaceId);
         return res.member;
       } catch (error) {
         throw this.handleError(error);
@@ -279,12 +292,14 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
       memberId: string,
     ): Promise<WorkspaceSuccessResult> {
       try {
-        return await this.makeRequest<WorkspaceSuccessResult>(
+        const result = await this.makeRequest<WorkspaceSuccessResult>(
           'DELETE',
           `/workspaces/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(memberId)}`,
           undefined,
           { cache: false },
         );
+        this._invalidateWorkspaceMembership(workspaceId);
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
@@ -301,15 +316,36 @@ export function OxyServicesWorkspacesMixin<T extends typeof OxyServicesBase>(Bas
       data: TransferWorkspaceOwnershipInput,
     ): Promise<WorkspaceSuccessResult> {
       try {
-        return await this.makeRequest<WorkspaceSuccessResult>(
+        const result = await this.makeRequest<WorkspaceSuccessResult>(
           'POST',
           `/workspaces/${encodeURIComponent(workspaceId)}/transfer-ownership`,
           data,
           { cache: false },
         );
+        // Ownership change alters roles in the member list AND the detail, and
+        // can change which workspaces the caller "owns" in the list view.
+        this._invalidateWorkspaceMembership(workspaceId);
+        this.clearCacheEntry('GET:/workspaces');
+        return result;
       } catch (error) {
         throw this.handleError(error);
       }
     }
+
+    /**
+     * Bust the cached member list and detail for a workspace after a membership
+     * mutation. The member list (`getWorkspaceMembers`) and the detail
+     * (`getWorkspace`, which can embed member counts) 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).
+     */
+    _invalidateWorkspaceMembership(workspaceId: string): void {
+      this.clearCacheEntry(`GET:/workspaces/${encodeURIComponent(workspaceId)}/members`);
+      this.clearCacheEntry(`GET:/workspaces/${encodeURIComponent(workspaceId)}`);
+    }
   };
 }

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

@@ -0,0 +1,147 @@
+/**
+ * Privacy / list cache-invalidation tests.
+ *
+ * The privacy reads cache their GET responses (identity-scoped):
+ *  - `getBlockedUsers()`     → `GET:/privacy/blocked`        (~1 min TTL)
+ *  - `getRestrictedUsers()`  → `GET:/privacy/restricted`     (~1 min TTL)
+ *  - `getPrivacySettings(id)`→ `GET:/privacy/<id>/privacy`   (~2 min TTL)
+ *
+ * Each corresponding write MUST invalidate the matching cached GET, otherwise a
+ * consumer that re-reads within the TTL window observes the STALE pre-write
+ * value (mirrors the follow/unfollow follow-status invalidation contract).
+ */
+
+import { OxyServices } from '../../OxyServices';
+
+/** Build a non-verified JWT whose payload decodes to the given claims. */
+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('privacy 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('busts the cached blocked list after blockUser', async () => {
+    // 1) Warm the cache: empty blocked list.
+    fetchMock.mockResolvedValueOnce(jsonResponse([]));
+    expect(await oxy.getBlockedUsers()).toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // A second read within the TTL is a cache hit (no extra network call).
+    await oxy.getBlockedUsers();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // 2) Block a user — must invalidate the cached list.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.blockUser('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // 3) Re-read MUST re-fetch and observe the new entry.
+    fetchMock.mockResolvedValueOnce(jsonResponse([{ blockedId: 'target-1' }]));
+    const after = await oxy.getBlockedUsers();
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after).toEqual([{ blockedId: 'target-1' }]);
+  });
+
+  it('busts the cached blocked list after unblockUser', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([{ blockedId: 'target-1' }]));
+    await oxy.getBlockedUsers();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.unblockUser('target-1');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse([]));
+    expect(await oxy.getBlockedUsers()).toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+  });
+
+  it('busts the cached restricted list after restrictUser / unrestrictUser', async () => {
+    fetchMock.mockResolvedValueOnce(jsonResponse([]));
+    await oxy.getRestrictedUsers();
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.restrictUser('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse([{ restrictedId: 'target-2' }]));
+    expect(await oxy.getRestrictedUsers()).toEqual([{ restrictedId: 'target-2' }]);
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.unrestrictUser('target-2');
+    expect(fetchMock).toHaveBeenCalledTimes(4);
+
+    fetchMock.mockResolvedValueOnce(jsonResponse([]));
+    expect(await oxy.getRestrictedUsers()).toEqual([]);
+    expect(fetchMock).toHaveBeenCalledTimes(5);
+  });
+
+  it('busts the cached privacy settings (same id) after updatePrivacySettings', async () => {
+    // Warm the settings cache for an explicit id (avoids a getCurrentUser call).
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: false }));
+    expect(await oxy.getPrivacySettings('me')).toEqual({ isPrivateAccount: false });
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Cache hit on the second read.
+    await oxy.getPrivacySettings('me');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+
+    // Update — must invalidate `GET:/privacy/me/privacy`.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: true }));
+    await oxy.updatePrivacySettings({ isPrivateAccount: true }, 'me');
+    expect(fetchMock).toHaveBeenCalledTimes(2);
+
+    // Re-read MUST re-fetch and observe the new value.
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: true }));
+    const after = await oxy.getPrivacySettings('me');
+    expect(fetchMock).toHaveBeenCalledTimes(3);
+    expect(after).toEqual({ isPrivateAccount: true });
+  });
+
+  it('invalidates the exact logical keys on block/restrict/settings writes', async () => {
+    const clearSpy = jest.spyOn(oxy, 'clearCacheEntry');
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.blockUser('u1');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/blocked');
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ message: 'ok' }));
+    await oxy.restrictUser('u2');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/restricted');
+
+    fetchMock.mockResolvedValueOnce(jsonResponse({ isPrivateAccount: true }));
+    await oxy.updatePrivacySettings({ isPrivateAccount: true }, 'me');
+    expect(clearSpy).toHaveBeenCalledWith('GET:/privacy/me/privacy');
+
+    clearSpy.mockRestore();
+  });
+});

package/src/models/interfaces.ts

@@ -29,8 +29,20 @@ export interface OxyConfig {
    */
   clientId?: string;
   // Performance & caching options
+  /**
+   * Enable the per-instance GET response cache. Defaults to `true` (5-minute
+   * TTL). Set to `false` to disable caching entirely for this instance — GET
+   * responses are then never stored and never served from cache, so every read
+   * hits the network. Useful for a linked backend client where another layer
+   * (e.g. React Query) is the single cache authority and the SDK's own cache
+   * would otherwise serve stale data after a write.
+   */
   enableCache?: boolean;
-  cacheTTL?: number; // Cache TTL in milliseconds (default: 5 minutes)
+  /**
+   * Cache TTL in milliseconds (default: 5 minutes). A value `<= 0` disables the
+   * per-instance GET response cache, equivalent to `enableCache: false`.
+   */
+  cacheTTL?: number;
   enableRequestDeduplication?: boolean;
   enableRetry?: boolean;
   maxRetries?: number;