@oxyhq/core 5.4.1 → 5.4.3

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

@@ -60,9 +60,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
         _serviceApiKey: string | null;
         _serviceApiSecret: string | null;
         /**
-         * Get profile by username
-         */
-        getProfileByUsername(username: string): Promise<User>;
+         * Get profile by username.
+         *
+         * @param username - The profile's username.
+         * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+         *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+         *   request bypasses BOTH the cache lookup and the post-fetch cache write
+         *   (see {@link HttpService.request}'s `cache` handling), so it neither
+         *   serves nor overwrites any entry already cached for this key — a
+         *   previously cached response (if one exists) is left in place until its
+         *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+         *   caller must observe a just-written change (e.g. a privacy/consent flag)
+         *   that would otherwise be masked by the TTL window.
+         */
+        getProfileByUsername(username: string, options?: {
+            cache?: boolean;
+        }): Promise<User>;
         /**
          * Lightweight username lookup for login flows.
          * Returns minimal public info: exists, color, avatar, name.displayName.
@@ -134,9 +147,22 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getSimilarProfiles(userId: string, limit?: number): Promise<User[]>;
         /**
-         * Get user by ID
-         */
-        getUserById(userId: string): Promise<User>;
+         * Get user by ID.
+         *
+         * @param userId - The target user's id.
+         * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+         *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+         *   request bypasses BOTH the cache lookup and the post-fetch cache write
+         *   (see {@link HttpService.request}'s `cache` handling), so it neither
+         *   serves nor overwrites any entry already cached for this key — a
+         *   previously cached response (if one exists) is left in place until its
+         *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+         *   caller must observe a just-written change (e.g. a privacy/consent flag)
+         *   that would otherwise be masked by the TTL window.
+         */
+        getUserById(userId: string, options?: {
+            cache?: boolean;
+        }): Promise<User>;
         /**
          * Fetch many users by id in one round-trip per chunk.
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.4.1",
+  "version": "5.4.3",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -94,7 +94,7 @@
     }
   },
   "dependencies": {
-    "@oxyhq/contracts": "^0.7.0",
+    "@oxyhq/contracts": "^0.8.0",
     "@oxyhq/protocol": "^0.1.1",
     "bip39": "^3.1.0",
     "buffer": "^6.0.3",

package/src/mixins/OxyServices.user.ts

@@ -101,12 +101,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     declare _serviceApiSecret: string | null;
 
     /**
-     * Get profile by username
-     */
-    async getProfileByUsername(username: string): Promise<User> {
+     * Get profile by username.
+     *
+     * @param username - The profile's username.
+     * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+     *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+     *   request bypasses BOTH the cache lookup and the post-fetch cache write
+     *   (see {@link HttpService.request}'s `cache` handling), so it neither
+     *   serves nor overwrites any entry already cached for this key — a
+     *   previously cached response (if one exists) is left in place until its
+     *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+     *   caller must observe a just-written change (e.g. a privacy/consent flag)
+     *   that would otherwise be masked by the TTL window.
+     */
+    async getProfileByUsername(username: string, options?: { cache?: boolean }): Promise<User> {
       try {
         const user = await this.makeRequest<User>('GET', `/profiles/username/${username}`, undefined, {
-          cache: true,
+          cache: options?.cache ?? true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache for profiles
         });
         return normalizeUserIdentity(user);
@@ -335,12 +346,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     }
 
     /**
-     * Get user by ID
-     */
-    async getUserById(userId: string): Promise<User> {
+     * Get user by ID.
+     *
+     * @param userId - The target user's id.
+     * @param options.cache - Defaults to `true` (5-minute TTL), matching prior
+     *   behavior. Pass `{ cache: false }` to force a registry-fresh read: the
+     *   request bypasses BOTH the cache lookup and the post-fetch cache write
+     *   (see {@link HttpService.request}'s `cache` handling), so it neither
+     *   serves nor overwrites any entry already cached for this key — a
+     *   previously cached response (if one exists) is left in place until its
+     *   own TTL expires or is explicitly invalidated elsewhere. Use this when a
+     *   caller must observe a just-written change (e.g. a privacy/consent flag)
+     *   that would otherwise be masked by the TTL window.
+     */
+    async getUserById(userId: string, options?: { cache?: boolean }): Promise<User> {
       try {
         const user = await this.makeRequest<User>('GET', `/users/${userId}`, undefined, {
-          cache: true,
+          cache: options?.cache ?? true,
           cacheTTL: 5 * 60 * 1000, // 5 minutes cache
         });
         return normalizeUserIdentity(user);

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

@@ -0,0 +1,121 @@
+/**
+ * Per-call cache-bypass tests for `getUserById` / `getProfileByUsername`.
+ *
+ * Both mixin methods cache their GET response for 5 minutes via
+ * `HttpService`'s identity-scoped TTL cache. A consumer that just wrote a
+ * setting readable through one of these endpoints (e.g. Mention's federation
+ * consent flag) needs a way to force a registry-fresh read instead of
+ * silently getting served the pre-write snapshot for up to 5 minutes.
+ *
+ * These tests pin down that:
+ *  - default behavior is UNCHANGED: a second call within the TTL is served
+ *    from cache (no second network call),
+ *  - `{ cache: false }` always hits the network, even immediately after a
+ *    cached call, and never overwrites the still-live cached entry — a
+ *    subsequent default-cache call keeps serving the ORIGINAL cached value.
+ */
+
+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('getUserById / getProfileByUsername cache bypass', () => {
+  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();
+  });
+
+  describe('getUserById', () => {
+    it('default call: a second read within the TTL is served from cache', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      const first = await oxy.getUserById('user-1');
+      expect(first.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      const second = await oxy.getUserById('user-1');
+      expect(second.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('{ cache: false } always hits the network, even right after a cached call', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      await oxy.getUserById('user-1');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice-renamed' }));
+      const fresh = await oxy.getUserById('user-1', { cache: false });
+      expect(fresh.username).toBe('alice-renamed');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+
+    it('{ cache: false } does not overwrite the still-live cached entry', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice' }));
+      await oxy.getUserById('user-1');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      // Bypass read observes server-side truth that has since changed...
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-1', username: 'alice-renamed' }));
+      await oxy.getUserById('user-1', { cache: false });
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      // ...but a plain cached read afterward still serves the ORIGINAL cached
+      // value — the bypass call never wrote to the cache slot.
+      const cached = await oxy.getUserById('user-1');
+      expect(cached.username).toBe('alice');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+
+  describe('getProfileByUsername', () => {
+    it('default call: a second read within the TTL is served from cache', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob' }));
+      const first = await oxy.getProfileByUsername('bob');
+      expect(first.id).toBe('user-2');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      const second = await oxy.getProfileByUsername('bob');
+      expect(second.id).toBe('user-2');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+
+    it('{ cache: false } always hits the network, even right after a cached call', async () => {
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob', bio: 'old' }));
+      await oxy.getProfileByUsername('bob');
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ id: 'user-2', username: 'bob', bio: 'new' }));
+      const fresh = await oxy.getProfileByUsername('bob', { cache: false });
+      expect((fresh as unknown as { bio: string }).bio).toBe('new');
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+    });
+  });
+});