@oxyhq/core 3.7.1 → 3.8.1

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

@@ -39,6 +39,15 @@ export interface BulkUnfollowResult {
 }
 export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T): {
     new (...args: any[]): {
+        /**
+         * Service-token request, implemented by the auth mixin earlier in the
+         * composition pipeline (see `mixins/index.ts`). The user mixin is typed
+         * against `OxyServicesBase`, which does not carry the auth mixin's methods,
+         * so this `declare` surfaces the inherited runtime method to TypeScript
+         * without re-implementing it. Used by `getUsersByIds` to authenticate the
+         * 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>;
         /**
          * Get profile by username
          */
@@ -117,6 +126,38 @@ export declare function OxyServicesUserMixin<T extends typeof OxyServicesBase>(B
          * Get user by ID
          */
         getUserById(userId: string): Promise<User>;
+        /**
+         * Fetch many users by id in one round-trip per chunk.
+         *
+         * Built for feed/hydration call sites that would otherwise issue one
+         * `getUserById` request per unique author (the classic M+1). Ids are
+         * deduplicated and validated (empty/blank ids dropped) before being split
+         * into chunks of {@link USERS_BY_IDS_CHUNK_SIZE} and POSTed to
+         * `/users/by-ids` as `{ ids }`. The server returns the matched users as a
+         * flat `User[]` (order is not guaranteed and the caller is expected to map
+         * 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".)
+         *
+         * Resilience: chunks are independent. A failed chunk is logged and skipped
+         * — the method returns every user that resolved successfully rather than
+         * discarding the whole call on one chunk's failure. An empty/whitespace-only
+         * input resolves immediately with `[]` and performs no network call.
+         *
+         * Not cached at the SDK layer: the response is keyed on a multi-id POST body
+         * (low hit rate) and the backend maintains its own per-id Redis cache.
+         */
+        getUsersByIds(ids: string[]): Promise<User[]>;
         /**
          * Get current user
          */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oxyhq/core",
-  "version": "3.7.1",
+  "version": "3.8.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

@@ -25,6 +25,12 @@ import { normalizeUserIdentity, normalizeUserIdentityOrNull } from '../utils/use
 import { logger } from '../utils/loggerUtils';
 import { extractErrorStatus } from '../utils/errorUtils';
 
+/**
+ * Maximum number of ids sent per `POST /users/by-ids` request. Matches the
+ * server-side batch cap; larger inputs are split into multiple chunked calls.
+ */
+const USERS_BY_IDS_CHUNK_SIZE = 100;
+
 /** Per-user outcome returned by `POST /users/follow/bulk`. */
 export interface BulkFollowEntry {
   /** The user ID that was processed. */
@@ -66,6 +72,22 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
     constructor(...args: any[]) {
       super(...(args as [any]));
     }
+
+    /**
+     * Service-token request, implemented by the auth mixin earlier in the
+     * composition pipeline (see `mixins/index.ts`). The user mixin is typed
+     * against `OxyServicesBase`, which does not carry the auth mixin's methods,
+     * so this `declare` surfaces the inherited runtime method to TypeScript
+     * without re-implementing it. Used by `getUsersByIds` to authenticate the
+     * server-to-server `/users/by-ids` bulk fetch with a bearer service token.
+     */
+    declare makeServiceRequest: <R = unknown>(
+      method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE',
+      url: string,
+      data?: unknown,
+      userId?: string,
+    ) => Promise<R>;
+
     /**
      * Get profile by username
      */
@@ -315,6 +337,71 @@ export function OxyServicesUserMixin<T extends typeof OxyServicesBase>(Base: T)
       }
     }
 
+    /**
+     * Fetch many users by id in one round-trip per chunk.
+     *
+     * Built for feed/hydration call sites that would otherwise issue one
+     * `getUserById` request per unique author (the classic M+1). Ids are
+     * deduplicated and validated (empty/blank ids dropped) before being split
+     * into chunks of {@link USERS_BY_IDS_CHUNK_SIZE} and POSTed to
+     * `/users/by-ids` as `{ ids }`. The server returns the matched users as a
+     * flat `User[]` (order is not guaranteed and the caller is expected to map
+     * 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".)
+     *
+     * Resilience: chunks are independent. A failed chunk is logged and skipped
+     * — the method returns every user that resolved successfully rather than
+     * discarding the whole call on one chunk's failure. An empty/whitespace-only
+     * input resolves immediately with `[]` and performs no network call.
+     *
+     * Not cached at the SDK layer: the response is keyed on a multi-id POST body
+     * (low hit rate) and the backend maintains its own per-id Redis cache.
+     */
+    async getUsersByIds(ids: string[]): Promise<User[]> {
+      const uniqueIds = Array.from(
+        new Set(ids.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)),
+      );
+      if (uniqueIds.length === 0) {
+        return [];
+      }
+
+      const chunks: string[][] = [];
+      for (let i = 0; i < uniqueIds.length; i += USERS_BY_IDS_CHUNK_SIZE) {
+        chunks.push(uniqueIds.slice(i, i + USERS_BY_IDS_CHUNK_SIZE));
+      }
+
+      // 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 });
+            return Array.isArray(users) ? users.map((user) => normalizeUserIdentity(user)) : [];
+          } catch (error: unknown) {
+            logger.warn('getUsersByIds: chunk failed, continuing with remaining chunks', {
+              method: 'getUsersByIds',
+              chunkSize: chunk.length,
+              status: extractErrorStatus(error),
+              error: error instanceof Error ? error.message : String(error),
+            });
+            return [];
+          }
+        }),
+      );
+
+      return settled.flat();
+    }
+
     /**
      * Get current user
      */