@oxyhq/core 3.4.18 → 3.5.0

package/dist/types/HttpService.d.ts

@@ -15,6 +15,7 @@
 import type { OxyConfig } from './models/interfaces';
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
+export type AccessTokenProvider = () => string | null;
 export interface RequestOptions {
     cache?: boolean;
     cacheTTL?: number;
@@ -52,6 +53,7 @@ export declare class HttpService {
     private tokenRefreshPromise;
     private tokenRefreshCooldownUntil;
     private authRefreshHandler;
+    private accessTokenProvider;
     /**
      * Fan-out listeners notified on EVERY access-token change on this instance:
      * explicit `setTokens`, `clearTokens`, an AuthManager-owned refresh, and the
@@ -64,6 +66,7 @@ export declare class HttpService {
     private _actingAsUserId;
     private requestMetrics;
     constructor(config: OxyConfig);
+    private syncAccessTokenFromProvider;
     /**
      * Robust FormData detection that works in browser, React Native, and
      * Node.js polyfill environments.
@@ -190,6 +193,7 @@ export declare class HttpService {
     getActingAs(): string | null;
     setTokens(accessToken: string): void;
     setAuthRefreshHandler(handler: AuthRefreshHandler | null): void;
+    setAccessTokenProvider(provider: AccessTokenProvider | null): void;
     clearTokens(): void;
     /**
      * Subscribe to access-token changes on this instance.

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, } 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,22 @@ 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;
+}
 export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
         /**
@@ -167,6 +183,15 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
             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 a user
          */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.4.18",
+  "version": "3.5.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/HttpService.ts

@@ -37,6 +37,7 @@ interface JwtPayload {
 
 export type AuthRefreshReason = 'preflight' | 'response-401';
 export type AuthRefreshHandler = (reason: AuthRefreshReason) => Promise<string | null>;
+export type AccessTokenProvider = () => string | null;
 
 /**
  * Structural type that captures the multipart-write surface every supported
@@ -171,6 +172,7 @@ export class HttpService {
   private tokenRefreshPromise: Promise<string | null> | null = null;
   private tokenRefreshCooldownUntil: number = 0;
   private authRefreshHandler: AuthRefreshHandler | null = null;
+  private accessTokenProvider: AccessTokenProvider | null = null;
 
   /**
    * Fan-out listeners notified on EVERY access-token change on this instance:
@@ -216,6 +218,29 @@ export class HttpService {
     );
   }
 
+  private syncAccessTokenFromProvider(): string | null {
+    if (!this.accessTokenProvider) {
+      return this.tokenStore.getAccessToken();
+    }
+
+    const providedToken = this.accessTokenProvider();
+    const currentToken = this.tokenStore.getAccessToken();
+
+    if (providedToken) {
+      if (providedToken !== currentToken) {
+        this.tokenStore.setTokens(providedToken);
+        this.notifyTokenChange();
+      }
+      return providedToken;
+    }
+
+    if (currentToken) {
+      this.clearTokens();
+    }
+
+    return null;
+  }
+
   /**
    * Robust FormData detection that works in browser, React Native, and
    * Node.js polyfill environments.
@@ -856,7 +881,7 @@ export class HttpService {
    * Get auth header with automatic token refresh
    */
   private async getAuthHeader(): Promise<string | null> {
-    const accessToken = this.tokenStore.getAccessToken();
+    const accessToken = this.syncAccessTokenFromProvider();
     if (!accessToken) {
       return null;
     }
@@ -993,6 +1018,10 @@ export class HttpService {
     this.authRefreshHandler = handler;
   }
 
+  setAccessTokenProvider(provider: AccessTokenProvider | null): void {
+    this.accessTokenProvider = provider;
+  }
+
   clearTokens(): void {
     this.tokenStore.clearTokens();
     this.tokenStore.clearCsrfToken();

package/src/OxyServices.base.ts

@@ -149,12 +149,10 @@ export class OxyServicesBase {
 
     syncToken(this.getAccessToken());
     const unsubscribe = this.onTokensChanged(syncToken);
+    client.setAccessTokenProvider(() => this.getAccessToken());
     client.setAuthRefreshHandler(async (reason: AuthRefreshReason) => {
       const refreshed = await this.httpService.refreshAccessToken(reason);
       if (!refreshed) {
-        if (reason === 'response-401') {
-          this.clearTokens();
-        }
         return null;
       }
 
@@ -167,6 +165,7 @@ export class OxyServicesBase {
       dispose: () => {
         unsubscribe();
         client.setAuthRefreshHandler(null);
+        client.setAccessTokenProvider(null);
         client.clearTokens();
       },
     };

package/src/__tests__/linkedClient.test.ts

@@ -1,9 +1,19 @@
 import { OxyServices } from '../OxyServices';
 
+interface FetchCall {
+  url: string;
+  init: RequestInit | undefined;
+}
+
 function createServices(): OxyServices {
   return new OxyServices({ baseURL: 'https://api.oxy.so' });
 }
 
+function createJwt(payload: Record<string, unknown>): string {
+  const encode = (value: unknown): string => Buffer.from(JSON.stringify(value)).toString('base64url');
+  return `${encode({ alg: 'HS256', typ: 'JWT' })}.${encode(payload)}.signature`;
+}
+
 function jsonResponse(data: unknown): Response {
   return new Response(JSON.stringify({ data }), {
     status: 200,
@@ -11,7 +21,28 @@ function jsonResponse(data: unknown): Response {
   });
 }
 
+function readHeaders(init: RequestInit | undefined): Record<string, string> {
+  const headers = init?.headers;
+  if (!headers) {
+    return {};
+  }
+  if (headers instanceof Headers) {
+    return Object.fromEntries(headers.entries());
+  }
+  if (Array.isArray(headers)) {
+    return Object.fromEntries(headers);
+  }
+  return headers as Record<string, string>;
+}
+
 describe('OxyServices.createLinkedClient', () => {
+  const originalFetch = globalThis.fetch;
+
+  afterEach(() => {
+    globalThis.fetch = originalFetch;
+    jest.restoreAllMocks();
+  });
+
   it('mirrors token changes from the session owner', () => {
     const oxy = createServices();
     const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
@@ -56,7 +87,7 @@ describe('OxyServices.createLinkedClient', () => {
     linked.dispose();
   });
 
-  it('clears the session owner when a linked response 401 cannot refresh', async () => {
+  it('keeps the session owner intact when a linked response 401 cannot refresh', async () => {
     const oxy = createServices();
     oxy.setTokens('stale_access');
     const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
@@ -64,9 +95,73 @@ describe('OxyServices.createLinkedClient', () => {
     const refreshed = await linked.client.refreshAccessToken('response-401');
 
     expect(refreshed).toBeNull();
-    expect(oxy.getAccessToken()).toBeNull();
+    expect(oxy.getAccessToken()).toBe('stale_access');
+    expect(linked.client.getAccessToken()).toBe('stale_access');
+
+    linked.dispose();
+  });
+
+  it('resynchronizes from the session owner after a linked app 401 clears the local token', async () => {
+    const calls: FetchCall[] = [];
+    let queueWriteAttempts = 0;
+    globalThis.fetch = async (input, init) => {
+      const url = String(input);
+      calls.push({ url, init });
+
+      if (url.endsWith('/csrf-token')) {
+        return new Response(JSON.stringify({ csrfToken: 'csrf_1' }), {
+          status: 200,
+          headers: { 'content-type': 'application/json' },
+        });
+      }
+
+      if (url.endsWith('/api/queue/current')) {
+        queueWriteAttempts += 1;
+        if (queueWriteAttempts === 1) {
+          return new Response(JSON.stringify({ error: 'MISSING_TOKEN' }), {
+            status: 401,
+            statusText: 'Unauthorized',
+            headers: { 'content-type': 'application/json' },
+          });
+        }
+      }
+
+      return jsonResponse({ ok: true });
+    };
+
+    const oxy = createServices();
+    const accessToken = createJwt({
+      userId: 'user_1',
+      exp: Math.floor(Date.now() / 1000) + 3600,
+    });
+    oxy.setTokens(accessToken);
+    oxy.getClient().setAuthRefreshHandler(async () => null);
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.syra.fm' });
+
+    await expect(linked.client.put('/api/queue/current', { trackId: 'track_1' }, { retry: false })).rejects.toMatchObject({
+      message: 'MISSING_TOKEN',
+      status: 401,
+    });
+
+    expect(oxy.getAccessToken()).toBe(accessToken);
     expect(linked.client.getAccessToken()).toBeNull();
 
+    await linked.client.put('/api/queue/current', { trackId: 'track_2' });
+
+    expect(calls.map((call) => call.url)).toEqual([
+      'https://api.syra.fm/api/queue/current',
+      'https://api.syra.fm/api/queue/current',
+    ]);
+    expect(linked.client.getAccessToken()).toBe(accessToken);
+
+    const firstHeaders = readHeaders(calls[0]?.init);
+    expect(firstHeaders.Authorization).toBe(`Bearer ${accessToken}`);
+    expect(firstHeaders['X-CSRF-Token']).toBeUndefined();
+
+    const secondHeaders = readHeaders(calls[1]?.init);
+    expect(secondHeaders.Authorization).toBe(`Bearer ${accessToken}`);
+    expect(secondHeaders['X-CSRF-Token']).toBeUndefined();
+
     linked.dispose();
   });
 
@@ -98,22 +193,17 @@ describe('OxyServices.createLinkedClient', () => {
   });
 
   it('joins linked base URLs with relative paths that omit the leading slash', async () => {
-    const originalFetch = globalThis.fetch;
     const fetchMock = jest.fn(async () => jsonResponse({ ok: true }));
     globalThis.fetch = fetchMock as unknown as typeof globalThis.fetch;
 
-    try {
-      const oxy = createServices();
-      const linked = oxy.createLinkedClient({ baseURL: 'https://api.mention.earth' });
+    const oxy = createServices();
+    const linked = oxy.createLinkedClient({ baseURL: 'https://api.mention.earth' });
 
-      await linked.client.get('profile/settings/me');
+    await linked.client.get('profile/settings/me');
 
-      expect(fetchMock).toHaveBeenCalledTimes(1);
-      expect(String(fetchMock.mock.calls[0]?.[0])).toBe('https://api.mention.earth/profile/settings/me');
+    expect(fetchMock).toHaveBeenCalledTimes(1);
+    expect(String(fetchMock.mock.calls[0]?.[0])).toBe('https://api.mention.earth/profile/settings/me');
 
-      linked.dispose();
-    } finally {
-      globalThis.fetch = originalFetch;
-    }
+    linked.dispose();
   });
 });

package/src/index.ts

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

package/src/mixins/OxyServices.user.ts

@@ -17,6 +17,24 @@ 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;
+}
+
 export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T) {
   return class extends Base {
     constructor(...args: any[]) {
@@ -404,6 +422,25 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * 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 {
+        return await this.makeRequest<BulkFollowResult>('POST', '/users/follow/bulk', { userIds }, { cache: false });
+      } catch (error) {
+        throw this.handleError(error);
+      }
+    }
+
     /**
      * Unfollow a user
      */