@oxyhq/core 5.1.0 → 5.1.1

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

@@ -48,6 +48,17 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * server-to-server `/users/by-ids` bulk fetch with a bearer service token.
          */
         makeServiceRequest: <R = unknown>(method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE", url: string, data?: unknown, userId?: string) => Promise<R>;
+        /**
+         * Raw service credentials stored by `configureServiceAuth()` on the auth
+         * mixin (earlier in the pipeline). Surfaced here via `declare` — for the
+         * same typing reason as `makeServiceRequest` above — so `getUsersByIds` can
+         * detect whether this instance is service-configured (a backend) and pick
+         * the bearer-service path, or fall back to the user-session path (a browser/
+         * RN client). Both are `null` until `configureServiceAuth(apiKey, apiSecret)`
+         * is called.
+         */
+        _serviceApiKey: string | null;
+        _serviceApiSecret: string | null;
         /**
          * Get profile by username
          */
@@ -138,16 +149,28 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * by `id`); each is run through `normalizeUserIdentity`, matching
          * `getUserById`.
          *
-         * **Service-token auth (required).** `/users/by-ids` is a server-to-server
-         * bulk fetch of PUBLIC user data and is called via `makeServiceRequest`,
-         * which attaches `Authorization: Bearer <serviceToken>`. oxy-api's CSRF
-         * middleware skips bearer-authenticated requests, so the calling client
-         * MUST be service-configured (`configureServiceAuth(apiKey, apiSecret)`)
-         * before invoking this method; otherwise `getServiceToken()` throws because
-         * no credentials are available. (A plain user-session request fails here:
-         * server-to-server there is no cookie jar, so the auto-attached
-         * `X-CSRF-Token` has no matching cookie and oxy-api rejects the POST with
-         * 403 "CSRF token missing".)
+         * **Dual-mode auth.** `/users/by-ids` is `optionalUserOrServiceAuth` on
+         * oxy-api: it accepts a service token, a user session, or an anonymous
+         * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
+         * payload (canonical `name.displayName` + `_count`) in every case — no
+         * viewer-specific fields. This method picks the path automatically:
+         * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
+         *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+         *   (attaches `Authorization: Bearer <serviceToken>`). This is the
+         *   server-to-server feed/notification hydration path (e.g. Mention's
+         *   `PostHydrationService`) and is unchanged.
+         * - **Plain client (browser / React Native with a user session):** when no
+         *   service credentials are configured, the chunk is fetched via
+         *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
+         *   middleware skips bearer-authenticated writes, and `makeRequest` only
+         *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
+         *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+         *   this method always used the service path, so every client-side caller
+         *   silently received `[]` because `getServiceToken()` had no credentials.
+         *
+         * Both paths run results through `normalizeUserIdentity` and unwrap the
+         * API's `{ data }` envelope identically (`makeServiceRequest` is literally
+         * `makeRequest` plus a bearer service header).
          *
          * Resilience: chunks are independent. A failed chunk is logged and skipped
          * — the method returns every user that resolved successfully rather than

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "5.1.0",
+  "version": "5.1.1",
   "description": "OxyHQ SDK Foundation — API client, authentication, cryptographic identity, and shared utilities",
   "main": "dist/cjs/index.js",
   "module": "dist/esm/index.js",

package/src/mixins/OxyServices.user.ts

@@ -88,6 +88,18 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       userId?: string,
     ) => Promise<R>;
 
+    /**
+     * Raw service credentials stored by `configureServiceAuth()` on the auth
+     * mixin (earlier in the pipeline). Surfaced here via `declare` — for the
+     * same typing reason as `makeServiceRequest` above — so `getUsersByIds` can
+     * detect whether this instance is service-configured (a backend) and pick
+     * the bearer-service path, or fall back to the user-session path (a browser/
+     * RN client). Both are `null` until `configureServiceAuth(apiKey, apiSecret)`
+     * is called.
+     */
+    declare _serviceApiKey: string | null;
+    declare _serviceApiSecret: string | null;
+
     /**
      * Get profile by username
      */
@@ -349,16 +361,28 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
      * by `id`); each is run through `normalizeUserIdentity`, matching
      * `getUserById`.
      *
-     * **Service-token auth (required).** `/users/by-ids` is a server-to-server
-     * bulk fetch of PUBLIC user data and is called via `makeServiceRequest`,
-     * which attaches `Authorization: Bearer <serviceToken>`. oxy-api's CSRF
-     * middleware skips bearer-authenticated requests, so the calling client
-     * MUST be service-configured (`configureServiceAuth(apiKey, apiSecret)`)
-     * before invoking this method; otherwise `getServiceToken()` throws because
-     * no credentials are available. (A plain user-session request fails here:
-     * server-to-server there is no cookie jar, so the auto-attached
-     * `X-CSRF-Token` has no matching cookie and oxy-api rejects the POST with
-     * 403 "CSRF token missing".)
+     * **Dual-mode auth.** `/users/by-ids` is `optionalUserOrServiceAuth` on
+     * oxy-api: it accepts a service token, a user session, or an anonymous
+     * caller, and returns the SAME public `{ data: PublicUserProfile[] }`
+     * payload (canonical `name.displayName` + `_count`) in every case — no
+     * viewer-specific fields. This method picks the path automatically:
+     * - **Service-configured host (backend):** when `configureServiceAuth(apiKey,
+     *   apiSecret)` has been called, the chunk is fetched via `makeServiceRequest`
+     *   (attaches `Authorization: Bearer <serviceToken>`). This is the
+     *   server-to-server feed/notification hydration path (e.g. Mention's
+     *   `PostHydrationService`) and is unchanged.
+     * - **Plain client (browser / React Native with a user session):** when no
+     *   service credentials are configured, the chunk is fetched via
+     *   `makeRequest`, which attaches the configured user bearer. oxy-api's CSRF
+     *   middleware skips bearer-authenticated writes, and `makeRequest` only
+     *   fetches a CSRF token for cookie-only (no-bearer) state-changing requests,
+     *   so the user-bearer POST is sent without CSRF and succeeds. Previously
+     *   this method always used the service path, so every client-side caller
+     *   silently received `[]` because `getServiceToken()` had no credentials.
+     *
+     * Both paths run results through `normalizeUserIdentity` and unwrap the
+     * API's `{ data }` envelope identically (`makeServiceRequest` is literally
+     * `makeRequest` plus a bearer service header).
      *
      * Resilience: chunks are independent. A failed chunk is logged and skipped
      * — the method returns every user that resolved successfully rather than
@@ -381,15 +405,23 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
         chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
       }
 
+      // A backend that called configureServiceAuth() uses the bearer-service
+      // path; any other caller (browser / RN with a user session) uses the
+      // user-bearer path. See the method doc for why the user path is CSRF-safe.
+      const useServiceAuth = Boolean(this._serviceApiKey && this._serviceApiSecret);
+
       // Run chunks concurrently; a single chunk failure must not sink the rest.
       const settled = await Promise.all(
         chunks.map(async (chunk): Promise<User[]> => {
           try {
-            const users = await this.makeServiceRequest<User[]>('POST', '/users/by-ids', { ids: chunk });
+            const users = useServiceAuth
+              ? await this.makeServiceRequest<User[]>('POST', '/users/by-ids', { ids: chunk })
+              : await this.makeRequest<User[]>('POST', '/users/by-ids', { ids: chunk }, { cache: false });
             return Array.isArray(users) ? users.map((user) => normalizeUserIdentity(user)) : [];
           } catch (error: unknown) {
             logger.warn('getUsersByIds: chunk failed, continuing with remaining chunks', {
               method: 'getUsersByIds',
+              mode: useServiceAuth ? 'service' : 'user',
               chunkSize: chunk.length,
               status: extractErrorStatus(error),
               error: error instanceof Error ? error.message : String(error),

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

@@ -0,0 +1,149 @@
+/**
+ * `getUsersByIds` dual-mode auth tests.
+ *
+ * `POST /users/by-ids` is `optionalUserOrServiceAuth` on oxy-api and returns
+ * the identical public `{ data: PublicUserProfile[] }` shape for both a service
+ * token and a user session. The SDK method must therefore:
+ *  - use the bearer-SERVICE path (`makeServiceRequest`) when the instance was
+ *    configured via `configureServiceAuth()` (the backend / hydration case), and
+ *  - use the USER path (`makeRequest('POST', ..., { cache: false })`) otherwise
+ *    (a browser / RN client with only a user session). Before the dual-mode fix
+ *    the method always took the service path, so every client-side caller got
+ *    `[]` because `getServiceToken()` had no credentials.
+ *
+ * Both paths must dedup + chunk, map every result through `normalizeUserIdentity`
+ * (so `name.displayName` is present), and tolerate a per-chunk failure without
+ * sinking the rest. `makeRequest` / `makeServiceRequest` are stubbed so the
+ * tests run with no network.
+ */
+
+import { OxyServices } from '../../OxyServices';
+import type { User } from '../../models/interfaces';
+
+const makeRawUser = (id: string): User =>
+  // The wire payload is a PublicUserProfile with server-owned name.displayName.
+  // Cast through the User shape the API returns post-unwrap.
+  ({
+    id,
+    username: `user_${id}`,
+    name: { displayName: `Display ${id}` },
+    _count: { followers: 1, following: 2 },
+  }) as unknown as User;
+
+describe('OxyServices.getUsersByIds — dual-mode auth', () => {
+  let oxy: OxyServices;
+  let makeRequestSpy: jest.SpyInstance;
+  let makeServiceRequestSpy: jest.SpyInstance;
+
+  beforeEach(() => {
+    oxy = new OxyServices({ baseURL: 'http://test.invalid' });
+    makeRequestSpy = jest.spyOn(oxy, 'makeRequest');
+    makeServiceRequestSpy = jest.spyOn(
+      oxy as unknown as { makeServiceRequest: jest.Mock },
+      'makeServiceRequest',
+    );
+  });
+
+  afterEach(() => {
+    jest.restoreAllMocks();
+  });
+
+  it('returns [] and performs no network call for empty / whitespace input', async () => {
+    await expect(oxy.getUsersByIds([])).resolves.toEqual([]);
+    await expect(oxy.getUsersByIds(['', '   '])).resolves.toEqual([]);
+    expect(makeRequestSpy).not.toHaveBeenCalled();
+    expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+  });
+
+  describe('without service credentials (client / user-session path)', () => {
+    it('uses makeRequest with the user bearer and cache:false', async () => {
+      makeRequestSpy.mockResolvedValueOnce([makeRawUser('a'), makeRawUser('b')]);
+
+      const result = await oxy.getUsersByIds(['a', 'b']);
+
+      expect(makeServiceRequestSpy).not.toHaveBeenCalled();
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/users/by-ids',
+        { ids: ['a', 'b'] },
+        { cache: false },
+      );
+      // normalizeUserIdentity ran on every entry (display name preserved).
+      expect(result).toHaveLength(2);
+      expect(result[0].name.displayName).toBe('Display a');
+      expect(result[1].id).toBe('b');
+    });
+
+    it('de-duplicates ids and drops blanks before the request', async () => {
+      makeRequestSpy.mockResolvedValueOnce([makeRawUser('a')]);
+
+      await oxy.getUsersByIds(['a', 'a', '   ', 'a']);
+
+      expect(makeRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeRequestSpy).toHaveBeenCalledWith(
+        'POST',
+        '/users/by-ids',
+        { ids: ['a'] },
+        { cache: false },
+      );
+    });
+  });
+
+  describe('with service credentials (backend / hydration path)', () => {
+    beforeEach(() => {
+      oxy.configureServiceAuth('oxy_dk_key', 'secret');
+    });
+
+    it('uses makeServiceRequest and never the user path — unchanged behavior', async () => {
+      makeServiceRequestSpy.mockResolvedValueOnce([makeRawUser('a'), makeRawUser('b')]);
+
+      const result = await oxy.getUsersByIds(['a', 'b']);
+
+      expect(makeRequestSpy).not.toHaveBeenCalled();
+      expect(makeServiceRequestSpy).toHaveBeenCalledTimes(1);
+      expect(makeServiceRequestSpy).toHaveBeenCalledWith('POST', '/users/by-ids', {
+        ids: ['a', 'b'],
+      });
+      expect(result).toHaveLength(2);
+      expect(result[0].name.displayName).toBe('Display a');
+    });
+  });
+
+  describe('chunking + resilience (applies to both modes)', () => {
+    it('chunks at 100 ids per request on the user path and flattens results', async () => {
+      const ids = Array.from({ length: 250 }, (_, i) => `id-${i}`);
+      makeRequestSpy.mockImplementation(
+        async (
+          _method: string,
+          _url: string,
+          data?: { ids: string[] },
+        ): Promise<User[]> => (data?.ids ?? []).map((id) => makeRawUser(id)),
+      );
+
+      const result = await oxy.getUsersByIds(ids);
+
+      // 250 unique ids => 100 + 100 + 50 across three POSTs.
+      expect(makeRequestSpy).toHaveBeenCalledTimes(3);
+      const chunkSizes = makeRequestSpy.mock.calls.map(
+        (call) => (call[2] as { ids: string[] }).ids.length,
+      );
+      expect(chunkSizes).toEqual([100, 100, 50]);
+      expect(result).toHaveLength(250);
+    });
+
+    it('skips a failed chunk and returns the users that resolved (user path)', async () => {
+      const ids = Array.from({ length: 150 }, (_, i) => `id-${i}`);
+      makeRequestSpy
+        .mockResolvedValueOnce([makeRawUser('id-0')])
+        .mockRejectedValueOnce(new Error('chunk boom'));
+
+      const result = await oxy.getUsersByIds(ids);
+
+      expect(makeRequestSpy).toHaveBeenCalledTimes(2);
+      // The failed second chunk contributes nothing; the first survives.
+      expect(result).toHaveLength(1);
+      expect(result[0].id).toBe('id-0');
+    });
+  });
+});