@oxyhq/core 3.8.0 → 3.8.2

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;

package/src/utils/cache.ts

@@ -91,11 +91,18 @@ export class TTLCache<T> {
    * Set a value in cache
    * @param key Cache key
    * @param data Data to cache
-   * @param ttl Optional TTL override (uses default if not provided)
+   * @param ttl Optional TTL override (uses default if not provided). An
+   *   explicit `0` or negative value is honored as "already expired" — the
+   *   entry is stored with `expiresAt <= now`, so the next `get`/`has` treats
+   *   it as a miss — rather than silently falling back to the default TTL.
    */
   set(key: string, data: T, ttl?: number): void {
     const now = Date.now();
-    const expiresAt = now + (ttl || this.defaultTTL);
+    // Distinguish "no override provided" (undefined → use default) from an
+    // explicit `0`/negative (do not cache). `ttl || this.defaultTTL` collapsed
+    // both into the default, making `cacheTTL:0` impossible to honor.
+    const effectiveTTL = ttl === undefined ? this.defaultTTL : ttl;
+    const expiresAt = now + effectiveTTL;
     this.cache.set(key, { data, timestamp: now, expiresAt });
   }