@oxyhq/core 3.8.1 → 3.9.0

package/dist/types/HttpService.d.ts

@@ -46,6 +46,15 @@ export declare class HttpService {
     private baseURL;
     private tokenStore;
     private cache;
+    /**
+     * When true, the per-instance GET response cache is OFF: GET responses are
+     * never read from nor written to {@link cache}, so every request hits the
+     * network. Set from `config.enableCache === false` OR `config.cacheTTL <= 0`.
+     * A disabled instance does not register its cache for the global cleanup
+     * interval (nothing ever lands in it). Request deduplication is unaffected —
+     * concurrent identical in-flight requests still collapse into one.
+     */
+    private readonly cacheDisabled;
     private deduplicator;
     private requestQueue;
     private logger;

package/dist/types/OxyServices.base.d.ts

@@ -52,6 +52,18 @@ export declare class OxyServicesBase {
      * OxyServices instance mounted in OxyProvider. The returned client has its own
      * base URL, cache and request queue, but its bearer token is kept in lockstep
      * with this session and its 401 refresh path delegates back to this session.
+     *
+     * **GET response caching is OFF by default for linked clients.** The SDK's
+     * per-instance GET cache is only safe where the SDK OWNS invalidation: on the
+     * canonical OxyServices client, every mutation (`updateProfile`, `followUser`,
+     * `blockUser`, …) busts the matching cached GET. A linked client targets the
+     * consuming app's OWN backend (`api.mention.earth`, `api.syra.fm`, …), whose
+     * resources and write endpoints the SDK has no knowledge of — so it cannot
+     * invalidate them, and a cached GET there would silently serve stale data
+     * after the app mutates its own data. Caching is therefore unsafe-by-construction
+     * here and is left to the consumer's own layer (React Query / stores), which
+     * owns its invalidation. Pass `createLinkedClient({ baseURL, enableCache: true })`
+     * to explicitly opt back in when the consumer accepts that responsibility.
      */
     createLinkedClient(config: OxyConfig): LinkedHttpClient;
     /**

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

@@ -363,6 +363,32 @@ export declare function OxyServicesApplicationsMixin<T extends typeof OxyService
          * @param period - Time window (defaults to the server default).
          */
         getApplicationUsage(applicationId: string, period?: ApplicationUsagePeriod): Promise<ApplicationUsageStats>;
+        /**
+         * Bust every cached application list. `getApplications(workspaceId?)` keys
+         * the unscoped list as `GET:/applications` and each workspace-scoped list as
+         * `GET:/applications?workspaceId=<id>` (the query string is part of the URL
+         * path). A change to list membership (create/delete/ownership transfer)
+         * invalidates all of them, so we clear the unscoped entry plus every
+         * `?workspaceId=` variant via a prefix sweep. The prefix `GET:/applications?`
+         * matches only the query-string list variants, never the `GET:/applications/<id>…`
+         * detail/sub-resource keys.
+         *
+         * 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).
+         */
+        _invalidateApplicationLists(): void;
+        /**
+         * Bust the cached member list and detail for an application after a
+         * membership mutation. The member list (`getApplicationMembers`) and the
+         * detail (`getApplication`, which can embed member counts) both go stale
+         * when the member set or a member's role changes.
+         *
+         * Internal helper (leading underscore); see `_invalidateApplicationLists`
+         * for why this is public rather than `private`.
+         */
+        _invalidateApplicationMembership(applicationId: string): void;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

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

@@ -129,19 +129,33 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
          */
         getCollections(userId?: string): Promise<Collection[]>;
         /**
-         * 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.
          */
         saveItem(itemId: string, itemType: string, collectionId?: string): Promise<SavedItem>;
         /**
-         * 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`).
          */
         removeSavedItem(saveId: string): Promise<void>;
         /**
-         * Create a collection
+         * Create a collection.
+         *
+         * Busts the cached own collections list (`GET /collections`) so the new
+         * collection appears on the next read.
          */
         createCollection(name: string, description?: string): Promise<Collection>;
         /**
-         * Delete a collection
+         * Delete a collection.
+         *
+         * Busts the cached own collections list so the deleted collection is
+         * gone on the next read (see `createCollection`).
          */
         deleteCollection(collectionId: string): Promise<void>;
         /**
@@ -153,11 +167,18 @@ export declare function OxyServicesFeaturesMixin<T extends typeof OxyServicesBas
          */
         getUserHistory(userId?: string, limit?: number, offset?: number): Promise<HistoryItem[]>;
         /**
-         * 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.
          */
         clearUserHistory(): Promise<void>;
         /**
-         * 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.
          */
         deleteHistoryItem(itemId: string): Promise<void>;
         /**

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

@@ -36,7 +36,9 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
          * 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.
          */
         createManagedAccount(data: CreateManagedAccountInput): Promise<ManagedAccount>;
         /**
@@ -50,17 +52,27 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
         /**
          * 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.
          */
         updateManagedAccount(accountId: string, data: Partial<CreateManagedAccountInput>): Promise<ManagedAccount>;
         /**
          * Delete a managed account permanently.
          * Requires owner role.
+         *
+         * Invalidates the cached detail and list responses so the deleted account
+         * is not served from cache.
          */
         deleteManagedAccount(accountId: string): Promise<void>;
         /**
          * 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'
@@ -70,6 +82,9 @@ export declare function OxyServicesManagedAccountsMixin<T extends typeof OxyServ
          * 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
          */

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

@@ -27,7 +27,13 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
          */
         getBlockedUsers(): Promise<BlockedUser[]>;
         /**
-         * 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
          */
@@ -35,7 +41,10 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
             message: string;
         }>;
         /**
-         * 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
          */
@@ -54,7 +63,13 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
          */
         getRestrictedUsers(): Promise<RestrictedUser[]>;
         /**
-         * 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
          */
@@ -62,7 +77,10 @@ export declare function OxyServicesPrivacyMixin<T extends typeof OxyServicesBase
             message: string;
         }>;
         /**
-         * 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
          */

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

@@ -182,7 +182,14 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          */
         getPrivacySettings(userId?: string): Promise<PrivacySettings>;
         /**
-         * 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)
          */

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

@@ -151,6 +151,18 @@ export declare function OxyServicesWorkspacesMixin<T extends typeof OxyServicesB
          * @param data - Target user id.
          */
         transferWorkspaceOwnership(workspaceId: string, data: TransferWorkspaceOwnershipInput): Promise<WorkspaceSuccessResult>;
+        /**
+         * 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;
         httpService: import("../HttpService").HttpService;
         cloudURL: string;
         config: import("../OxyServices.base").OxyConfig;

package/dist/types/models/interfaces.d.ts

@@ -27,7 +27,19 @@ export interface OxyConfig {
      * bounce (which uses the RP origin, not this registered client id).
      */
     clientId?: string;
+    /**
+     * 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;
+    /**
+     * 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;

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

@@ -59,7 +59,10 @@ export declare 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;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.8.1",
+  "version": "3.9.0",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",
@@ -125,9 +125,6 @@
     },
     "express": {
       "optional": true
-    },
-    "express-rate-limit": {
-      "optional": true
     }
   },
   "devDependencies": {

package/src/HttpService.ts

@@ -202,6 +202,15 @@ export class HttpService {
   private baseURL: string;
   private tokenStore: TokenStore;
   private cache: TTLCache<any>;
+  /**
+   * When true, the per-instance GET response cache is OFF: GET responses are
+   * never read from nor written to {@link cache}, so every request hits the
+   * network. Set from `config.enableCache === false` OR `config.cacheTTL <= 0`.
+   * A disabled instance does not register its cache for the global cleanup
+   * interval (nothing ever lands in it). Request deduplication is unaffected —
+   * concurrent identical in-flight requests still collapse into one.
+   */
+  private readonly cacheDisabled: boolean;
   private deduplicator: RequestDeduplicator;
   private requestQueue: RequestQueue;
   private logger: SimpleLogger;
@@ -252,9 +261,19 @@ export class HttpService {
       'HttpService'
     );
 
-    // Initialize performance infrastructure
-    this.cache = new TTLCache<any>(config.cacheTTL || 5 * 60 * 1000);
-    registerCacheForCleanup(this.cache);
+    // Initialize performance infrastructure. The per-instance GET response
+    // cache is disabled when the consumer explicitly opts out
+    // (`enableCache: false`) or asks for a non-positive TTL (`cacheTTL <= 0`).
+    // When disabled, nothing is ever stored, so there is no reason to register
+    // the cache for the global cleanup interval. Default (config unset) keeps
+    // caching ON with the 5-minute TTL — unchanged for existing consumers.
+    this.cacheDisabled =
+      config.enableCache === false ||
+      (typeof config.cacheTTL === 'number' && config.cacheTTL <= 0);
+    this.cache = new TTLCache<any>(config.cacheTTL && config.cacheTTL > 0 ? config.cacheTTL : 5 * 60 * 1000);
+    if (!this.cacheDisabled) {
+      registerCacheForCleanup(this.cache);
+    }
     this.deduplicator = new RequestDeduplicator();
     this.requestQueue = new RequestQueue(
       config.maxConcurrentRequests || 10,
@@ -352,13 +371,18 @@ export class HttpService {
       params,
       timeout = this.config.requestTimeout || DEFAULT_REQUEST_TIMEOUT_MS,
       signal,
-      cache = method === 'GET',
+      cache: cacheRequested = method === 'GET',
       cacheTTL,
       deduplicate = true,
       retry = this.config.enableRetry !== false,
       maxRetries = this.config.maxRetries || 3,
     } = config;
 
+    // A per-instance disabled cache (`enableCache:false` / `cacheTTL<=0`)
+    // overrides any per-request `cache:true`: nothing is read from nor written
+    // to the response cache. Request deduplication below is unaffected.
+    const cache = cacheRequested && !this.cacheDisabled;
+
     // Generate cache key (optimized for large objects)
     const cacheKey = cache ? this.generateCacheKey(method, url, data || params) : null;
 

package/src/OxyServices.base.ts

@@ -129,9 +129,23 @@ export class OxyServicesBase {
    * OxyServices instance mounted in OxyProvider. The returned client has its own
    * base URL, cache and request queue, but its bearer token is kept in lockstep
    * with this session and its 401 refresh path delegates back to this session.
+   *
+   * **GET response caching is OFF by default for linked clients.** The SDK's
+   * per-instance GET cache is only safe where the SDK OWNS invalidation: on the
+   * canonical OxyServices client, every mutation (`updateProfile`, `followUser`,
+   * `blockUser`, …) busts the matching cached GET. A linked client targets the
+   * consuming app's OWN backend (`api.mention.earth`, `api.syra.fm`, …), whose
+   * resources and write endpoints the SDK has no knowledge of — so it cannot
+   * invalidate them, and a cached GET there would silently serve stale data
+   * after the app mutates its own data. Caching is therefore unsafe-by-construction
+   * here and is left to the consumer's own layer (React Query / stores), which
+   * owns its invalidation. Pass `createLinkedClient({ baseURL, enableCache: true })`
+   * to explicitly opt back in when the consumer accepts that responsibility.
    */
   public createLinkedClient(config: OxyConfig): LinkedHttpClient {
-    const client = new HttpService(config);
+    // Default the GET cache OFF unless the caller explicitly opts in (see the
+    // method doc): the SDK cannot invalidate the consumer backend's resources.
+    const client = new HttpService({ ...config, enableCache: config.enableCache ?? false });
 
     const syncToken = (accessToken: string | null): void => {
       const currentAccessToken = client.getAccessToken();

package/src/__tests__/httpServiceCache.test.ts

@@ -266,4 +266,72 @@ describe('HttpService identity-scoped response cache', () => {
       expect(cacheWarnings.length).toBe(0);
     });
   });
+
+  /**
+   * `enableCache: false` (or `cacheTTL <= 0`) must fully disable the
+   * per-instance GET response cache: every read hits the network, even when the
+   * per-request `cache: true` flag is set. This is the lever Mention's linked
+   * backend client uses to make React Query the single cache authority and
+   * avoid stale-after-write reads from the SDK's own cache. Default behavior
+   * (config unset) is unchanged — caching stays ON.
+   */
+  describe('per-instance cache disable', () => {
+    it('never serves a cached GET when enableCache is false', async () => {
+      const http = new HttpService({
+        baseURL: 'http://test.invalid',
+        enableRetry: false,
+        requestTimeout: 1000,
+        enableCache: false,
+      });
+      http.setTokens(makeJwt({ userId: 'user-1' }));
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await http.get<{ v: number }>('/some/resource', { cache: true });
+      expect(first.v).toBe(1);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      // A second identical read with cache:true must STILL hit the network,
+      // because the instance cache is disabled. Nothing is ever stored.
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
+      const second = await http.get<{ v: number }>('/some/resource', { cache: true });
+      expect(second.v).toBe(2);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(http.getCacheStats().size).toBe(0);
+    });
+
+    it('treats cacheTTL <= 0 as a disabled cache', async () => {
+      const http = new HttpService({
+        baseURL: 'http://test.invalid',
+        enableRetry: false,
+        requestTimeout: 1000,
+        cacheTTL: 0,
+      });
+      http.setTokens(makeJwt({ userId: 'user-1' }));
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      await http.get('/some/resource', { cache: true });
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
+      await http.get('/some/resource', { cache: true });
+
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+      expect(http.getCacheStats().size).toBe(0);
+    });
+
+    it('still caches by default (config unset) — no behavior change', async () => {
+      const http = new HttpService({
+        baseURL: 'http://test.invalid',
+        enableRetry: false,
+        requestTimeout: 1000,
+      });
+      http.setTokens(makeJwt({ userId: 'user-1' }));
+
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await http.get<{ v: number }>('/some/resource', { cache: true });
+      // Second read is a warm cache hit — no second network call.
+      const second = await http.get<{ v: number }>('/some/resource', { cache: true });
+
+      expect(first).toEqual(second);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+    });
+  });
 });

package/src/__tests__/linkedClient.test.ts

@@ -206,4 +206,65 @@ describe('OxyServices.createLinkedClient', () => {
 
     linked.dispose();
   });
+
+  /**
+   * GET response caching is OFF by default for linked clients: the SDK cannot
+   * invalidate the consumer backend's resources, so a cached GET there would
+   * serve stale data after the app mutates its own data. The consumer's own
+   * layer (React Query / stores) owns caching. An explicit `enableCache: true`
+   * opts back in.
+   */
+  describe('linked client GET cache default', () => {
+    it('does NOT cache GETs by default — every read hits the network', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+      const oxy = createServices();
+      const accessToken = createJwt({
+        userId: 'user_1',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      });
+      oxy.setTokens(accessToken);
+      const linked = oxy.createLinkedClient({ baseURL: 'https://api.mention.earth' });
+
+      // Two identical GETs with cache:true — both MUST hit the network because
+      // the linked client's cache is disabled by default.
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 2 }));
+      const second = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+
+      expect(first.v).toBe(1);
+      expect(second.v).toBe(2);
+      expect(fetchMock).toHaveBeenCalledTimes(2);
+
+      linked.dispose();
+    });
+
+    it('caches GETs when the caller explicitly opts in with enableCache: true', async () => {
+      const fetchMock = jest.fn();
+      globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
+
+      const oxy = createServices();
+      const accessToken = createJwt({
+        userId: 'user_1',
+        exp: Math.floor(Date.now() / 1000) + 3600,
+      });
+      oxy.setTokens(accessToken);
+      const linked = oxy.createLinkedClient({
+        baseURL: 'https://api.mention.earth',
+        enableCache: true,
+      });
+
+      // Second identical GET is a warm cache hit — only one network call.
+      fetchMock.mockResolvedValueOnce(jsonResponse({ v: 1 }));
+      const first = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+      const second = await linked.client.get<{ v: number }>('/feed/mtn', { cache: true });
+
+      expect(first).toEqual(second);
+      expect(fetchMock).toHaveBeenCalledTimes(1);
+
+      linked.dispose();
+    });
+  });
 });