@embed-ai/sdk 0.1.2 → 0.1.3

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@embed-ai/sdk",
-  "version": "0.1.2",
-  "type": "module",
+  "version": "0.1.3",
+  "main": "src/index.js",
   "license": "BSD-3-Clause",
   "description": "The typescript sdk package for embed AI APIs.",
   "repository": {
@@ -30,7 +30,7 @@
     "coverage": "vitest --coverage"
   },
   "dependencies": {
-    "@embed-ai/types": "^0.1.1"
+    "@embed-ai/types": "^0.1.2"
   },
   "peerDependencies": {
     "effect": ">=3.0.0"

package/src/client.d.ts

@@ -1,4 +1,5 @@
 import { FeedNamespace } from "./feed/namespace.js";
+import { SearchNamespace } from "./search/namespace.js";
 declare const NetworkError_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").Equals<A, {}> extends true ? void : { readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }) => import("effect/Cause").YieldableError & {
     readonly _tag: "NetworkError";
 } & Readonly<A>;
@@ -105,7 +106,7 @@ export interface mbdClientConfig {
     readonly retry?: RetryConfig;
 }
 /**
- * Main Embed API client providing access to personalized feeds and feed management
+ * Main Embed API client providing access to personalized feeds, feed management, and search
  *
  * @example
  * ```typescript
@@ -121,11 +122,18 @@ export interface mbdClientConfig {
  *   name: 'My Custom Feed',
  *   description: 'A feed for my app'
  * })
+ *
+ * // Search for similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
  * ```
  */
 export declare class mbdClient {
     private http;
     readonly feed: FeedNamespace;
+    readonly search: SearchNamespace;
     constructor(token?: string, options?: mbdClientConfig);
 }
 /**
@@ -151,6 +159,12 @@ export declare class mbdClient {
  *   description: 'A feed for my app'
  * })
  *
+ * // Search for similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
+ *
  * // With configuration
  * const client = getClient('your-api-key', {
  *   retry: {

package/src/client.js

@@ -3,15 +3,14 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-exports.TimeoutError = exports.ParseError = exports.NetworkError = exports.HttpRequestError = void 0;
+exports.mbdClient = exports.TimeoutError = exports.ParseError = exports.HttpRequestError = exports.NetworkError = void 0;
 exports.getClient = getClient;
-exports.mbdClient = void 0;
-var _effect = require("effect");
-var Data = _interopRequireWildcard(require("effect/Data"));
-var Effect = _interopRequireWildcard(require("effect/Effect"));
-var Schedule = _interopRequireWildcard(require("effect/Schedule"));
-var _namespace = require("./feed/namespace.js");
-function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
+const effect_1 = /*#__PURE__*/require("effect");
+const Data = /*#__PURE__*/require("effect/Data");
+const Effect = /*#__PURE__*/require("effect/Effect");
+const Schedule = /*#__PURE__*/require("effect/Schedule");
+const namespace_js_1 = /*#__PURE__*/require("./feed/namespace.js");
+const namespace_js_2 = /*#__PURE__*/require("./search/namespace.js");
 // ============================================================================
 // ERROR TYPES
 // ============================================================================
@@ -19,25 +18,25 @@ function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r
  * Network-related errors (connection issues, DNS failures, etc.)
  */
 class NetworkError extends Data.TaggedError("NetworkError") {}
+exports.NetworkError = NetworkError;
 /**
  * HTTP response errors (4xx, 5xx status codes)
  */
-exports.NetworkError = NetworkError;
 class HttpRequestError extends Data.TaggedError("HttpRequestError") {}
+exports.HttpRequestError = HttpRequestError;
 /**
  * JSON parsing errors
  */
-exports.HttpRequestError = HttpRequestError;
 class ParseError extends Data.TaggedError("ParseError") {}
+exports.ParseError = ParseError;
 /**
  * Timeout errors
  */
-exports.ParseError = ParseError;
 class TimeoutError extends Data.TaggedError("TimeoutError") {}
+exports.TimeoutError = TimeoutError;
 /**
  * Default retry configuration
  */
-exports.TimeoutError = TimeoutError;
 const DEFAULT_RETRY_CONFIG = {
   exponentialBackoff: true,
   initialDelay: 1000,
@@ -77,7 +76,7 @@ class HttpClient {
    * Create a timeout effect that fails after the specified duration
    */
   createTimeoutEffect(timeoutMs) {
-    return (0, _effect.pipe)(Effect.sleep(`${timeoutMs} millis`), Effect.flatMap(() => Effect.fail(new TimeoutError({
+    return (0, effect_1.pipe)(Effect.sleep(`${timeoutMs} millis`), Effect.flatMap(() => Effect.fail(new TimeoutError({
       message: `Request timed out after ${timeoutMs}ms`,
       timeoutMs
     }))));
@@ -170,12 +169,12 @@ class HttpClient {
     } = this.config.retry;
     let baseSchedule;
     if (exponentialBackoff) {
-      baseSchedule = (0, _effect.pipe)(Schedule.exponential(`${initialDelay} millis`), Schedule.either(Schedule.spaced(`${maxDelay} millis`)), Schedule.compose(Schedule.recurs(maxRetries)));
+      baseSchedule = (0, effect_1.pipe)(Schedule.exponential(`${initialDelay} millis`), Schedule.either(Schedule.spaced(`${maxDelay} millis`)), Schedule.compose(Schedule.recurs(maxRetries)));
     } else {
-      baseSchedule = (0, _effect.pipe)(Schedule.spaced(`${initialDelay} millis`), Schedule.compose(Schedule.recurs(maxRetries)));
+      baseSchedule = (0, effect_1.pipe)(Schedule.spaced(`${initialDelay} millis`), Schedule.compose(Schedule.recurs(maxRetries)));
     }
     // Only retry on specific errors
-    return (0, _effect.pipe)(baseSchedule, Schedule.whileInput(error => {
+    return (0, effect_1.pipe)(baseSchedule, Schedule.whileInput(error => {
       switch (error._tag) {
         case "NetworkError":
           return true;
@@ -203,7 +202,7 @@ class HttpClient {
     const requestWithTimeout = Effect.race(fetchEffect, timeoutEffect);
     // Apply retry logic
     const retrySchedule = this.createRetrySchedule();
-    return (0, _effect.pipe)(requestWithTimeout, Effect.retry(retrySchedule), Effect.tapError(error => Effect.logError("HTTP request failed after retries", error)));
+    return (0, effect_1.pipe)(requestWithTimeout, Effect.retry(retrySchedule), Effect.tapError(error => Effect.logError("HTTP request failed after retries", error)));
   }
   /**
    * Make a POST request to the API with Effect-based error handling and retries
@@ -238,7 +237,7 @@ class HttpClient {
 // MAIN CLIENT
 // ============================================================================
 /**
- * Main Embed API client providing access to personalized feeds and feed management
+ * Main Embed API client providing access to personalized feeds, feed management, and search
  *
  * @example
  * ```typescript
@@ -254,11 +253,18 @@ class HttpClient {
  *   name: 'My Custom Feed',
  *   description: 'A feed for my app'
  * })
+ *
+ * // Search for similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
  * ```
  */
 class mbdClient {
   http;
   feed;
+  search;
   constructor(token, options) {
     if (!token && !options?.token) {
       throw new Error("Token is required");
@@ -268,9 +274,11 @@ class mbdClient {
       ...options
     };
     this.http = new HttpClient(config);
-    this.feed = new _namespace.FeedNamespace(this.http);
+    this.feed = new namespace_js_1.FeedNamespace(this.http);
+    this.search = new namespace_js_2.SearchNamespace(this.http);
   }
 }
+exports.mbdClient = mbdClient;
 /**
  * Get a new Embed Client instance
  *
@@ -294,6 +302,12 @@ class mbdClient {
  *   description: 'A feed for my app'
  * })
  *
+ * // Search for similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
+ *
  * // With configuration
  * const client = getClient('your-api-key', {
  *   retry: {
@@ -303,7 +317,6 @@ class mbdClient {
  * })
  * ```
  */
-exports.mbdClient = mbdClient;
 function getClient(token, options) {
   return new mbdClient(token, options);
 }

package/src/feed/index.js

@@ -1,39 +1,28 @@
 "use strict";
 
+var __createBinding = void 0 && (void 0).__createBinding || (Object.create ? function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  var desc = Object.getOwnPropertyDescriptor(m, k);
+  if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+    desc = {
+      enumerable: true,
+      get: function () {
+        return m[k];
+      }
+    };
+  }
+  Object.defineProperty(o, k2, desc);
+} : function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  o[k2] = m[k];
+});
+var __exportStar = void 0 && (void 0).__exportStar || function (m, exports) {
+  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-var _feed = require("./feed.js");
-Object.keys(_feed).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _feed[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _feed[key];
-    }
-  });
-});
-var _management = require("./management.js");
-Object.keys(_management).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _management[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _management[key];
-    }
-  });
-});
-var _namespace = require("./namespace.js");
-Object.keys(_namespace).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _namespace[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _namespace[key];
-    }
-  });
-});
+__exportStar(require("./feed.js"), exports);
+__exportStar(require("./management.js"), exports);
+__exportStar(require("./namespace.js"), exports);
 //# sourceMappingURL=index.js.map

package/src/feed/namespace.d.ts

@@ -1,4 +1,4 @@
-import type { CreateFeedOptions, FeedCreateUpdateResponse, FeedGetResponse, ForYouResponse, ListFeedsResponse, UpdateFeedOptions } from "@embed-ai/types";
+import type { CreateFeedOptions, FeedCreateUpdateResponse, FeedGetResponse, ForYouResponse, ListFeedsResponse } from "@embed-ai/types";
 import type { IHttpClient } from "../interfaces/index.js";
 import type { FeedOptions } from "./feed.js";
 /**
@@ -8,8 +8,8 @@ import type { FeedOptions } from "./feed.js";
  * ```typescript
  * const client = getClient('your-api-key')
  *
- * // Get personalized feed
- * const feed = await client.feed.byUserId('16085')
+ * // Get personalized feed based on the For-You template
+ * const feed = await client.feed.byUserId('16085', 'feed_390')
  *
  * // Create a custom feed
  * const customFeed = await client.feed.createConfig({
@@ -32,7 +32,7 @@ export declare class FeedNamespace {
      * @example
      * ```typescript
      * const client = getClient("your-api-key")
-     * const feed = await client.feed.byUserId("16085", {
+     * const feed = await client.feed.byUserId("16085", "feed_390", {
      *   top_k: 10,
      *   return_metadata: true
      * })
@@ -52,7 +52,7 @@ export declare class FeedNamespace {
      * @example
      * ```typescript
      * const client = getClient("your-api-key")
-     * const feed = await client.feed.byWalletAddress("0x1234...", {
+     * const feed = await client.feed.byWalletAddress("0x1234...", "feed_390", {
      *   top_k: 15,
      * })
      * console.log(feed[0].metadata?.author.username) // Access author username
@@ -124,8 +124,7 @@ export declare class FeedNamespace {
      * @example
      * ```typescript
      * const client = getClient("your-api-key")
-     * await client.feed.updateConfig({
-     *   config_id: "feed_123",
+     * await client.feed.updateConfig("feed_123", {
      *   name: "Updated Feed Name",
      *   config: {
      *     filters: {
@@ -136,6 +135,6 @@ export declare class FeedNamespace {
      * console.log("Feed updated successfully")
      * ```
      */
-    updateConfig(feedId: string, options: UpdateFeedOptions): Promise<void>;
+    updateConfig(feedId: string, options: CreateFeedOptions): Promise<void>;
 }
 //# sourceMappingURL=namespace.d.ts.map

package/src/feed/namespace.js

@@ -4,8 +4,8 @@ Object.defineProperty(exports, "__esModule", {
   value: true
 });
 exports.FeedNamespace = void 0;
-var _feed = require("./feed.js");
-var _management = require("./management.js");
+const feed_js_1 = /*#__PURE__*/require("./feed.js");
+const management_js_1 = /*#__PURE__*/require("./management.js");
 /**
  * Feed namespace containing all feed-related operations
  *
@@ -13,8 +13,8 @@ var _management = require("./management.js");
  * ```typescript
  * const client = getClient('your-api-key')
  *
- * // Get personalized feed
- * const feed = await client.feed.byUserId('16085')
+ * // Get personalized feed based on the For-You template
+ * const feed = await client.feed.byUserId('16085', 'feed_390')
  *
  * // Create a custom feed
  * const customFeed = await client.feed.createConfig({
@@ -42,7 +42,7 @@ class FeedNamespace {
    * @example
    * ```typescript
    * const client = getClient("your-api-key")
-   * const feed = await client.feed.byUserId("16085", {
+   * const feed = await client.feed.byUserId("16085", "feed_390", {
    *   top_k: 10,
    *   return_metadata: true
    * })
@@ -51,7 +51,7 @@ class FeedNamespace {
    * ```
    */
   async byUserId(userId, feedId, options) {
-    return (0, _feed.byUserId)(this.http, userId, feedId, options);
+    return (0, feed_js_1.byUserId)(this.http, userId, feedId, options);
   }
   /**
    * Get personalized "For You" feed by wallet address
@@ -64,7 +64,7 @@ class FeedNamespace {
    * @example
    * ```typescript
    * const client = getClient("your-api-key")
-   * const feed = await client.feed.byWalletAddress("0x1234...", {
+   * const feed = await client.feed.byWalletAddress("0x1234...", "feed_390", {
    *   top_k: 15,
    * })
    * console.log(feed[0].metadata?.author.username) // Access author username
@@ -72,7 +72,7 @@ class FeedNamespace {
    * ```
    */
   async byWalletAddress(walletAddress, feedId, options) {
-    return (0, _feed.byWalletAddress)(this.http, walletAddress, feedId, options);
+    return (0, feed_js_1.byWalletAddress)(this.http, walletAddress, feedId, options);
   }
   // ============================================================================
   // FEED MANAGEMENT METHODS
@@ -101,7 +101,7 @@ class FeedNamespace {
    * ```
    */
   async createConfig(options) {
-    return (0, _management.createConfig)(this.http, options);
+    return (0, management_js_1.createConfig)(this.http, options);
   }
   /**
    * Get a feed configuration by feedId
@@ -118,7 +118,7 @@ class FeedNamespace {
    * ```
    */
   async getConfig(feedId) {
-    return (0, _management.getConfig)(this.http, feedId);
+    return (0, management_js_1.getConfig)(this.http, feedId);
   }
   /**
    * List all feed configurations for the account
@@ -135,7 +135,7 @@ class FeedNamespace {
    * ```
    */
   async listConfigs(visibility = "private") {
-    return (0, _management.listConfigs)(this.http, visibility);
+    return (0, management_js_1.listConfigs)(this.http, visibility);
   }
   /**
    * Update an existing feed configuration
@@ -147,8 +147,7 @@ class FeedNamespace {
    * @example
    * ```typescript
    * const client = getClient("your-api-key")
-   * await client.feed.updateConfig({
-   *   config_id: "feed_123",
+   * await client.feed.updateConfig("feed_123", {
    *   name: "Updated Feed Name",
    *   config: {
    *     filters: {
@@ -160,7 +159,7 @@ class FeedNamespace {
    * ```
    */
   async updateConfig(feedId, options) {
-    return (0, _management.updateConfig)(this.http, feedId, options);
+    return (0, management_js_1.updateConfig)(this.http, feedId, options);
   }
 }
 exports.FeedNamespace = FeedNamespace;

package/src/index.js

@@ -3,48 +3,53 @@
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-Object.defineProperty(exports, "FeedNamespace", {
+exports.FeedNamespace = exports.TimeoutError = exports.ParseError = exports.NetworkError = exports.HttpRequestError = exports.mbdClient = exports.getClient = void 0;
+// Export the main client factory function
+var client_js_1 = /*#__PURE__*/require("./client.js");
+Object.defineProperty(exports, "getClient", {
   enumerable: true,
   get: function () {
-    return _namespace.FeedNamespace;
+    return client_js_1.getClient;
   }
 });
-Object.defineProperty(exports, "HttpRequestError", {
+Object.defineProperty(exports, "mbdClient", {
   enumerable: true,
   get: function () {
-    return _client.HttpRequestError;
+    return client_js_1.mbdClient;
   }
 });
-Object.defineProperty(exports, "NetworkError", {
+// Export error types for error handling
+var client_js_2 = /*#__PURE__*/require("./client.js");
+Object.defineProperty(exports, "HttpRequestError", {
   enumerable: true,
   get: function () {
-    return _client.NetworkError;
+    return client_js_2.HttpRequestError;
   }
 });
-Object.defineProperty(exports, "ParseError", {
+Object.defineProperty(exports, "NetworkError", {
   enumerable: true,
   get: function () {
-    return _client.ParseError;
+    return client_js_2.NetworkError;
   }
 });
-Object.defineProperty(exports, "TimeoutError", {
+Object.defineProperty(exports, "ParseError", {
   enumerable: true,
   get: function () {
-    return _client.TimeoutError;
+    return client_js_2.ParseError;
   }
 });
-Object.defineProperty(exports, "getClient", {
+Object.defineProperty(exports, "TimeoutError", {
   enumerable: true,
   get: function () {
-    return _client.getClient;
+    return client_js_2.TimeoutError;
   }
 });
-Object.defineProperty(exports, "mbdClient", {
+// Export feed namespace
+var namespace_js_1 = /*#__PURE__*/require("./feed/namespace.js");
+Object.defineProperty(exports, "FeedNamespace", {
   enumerable: true,
   get: function () {
-    return _client.mbdClient;
+    return namespace_js_1.FeedNamespace;
   }
 });
-var _client = require("./client.js");
-var _namespace = require("./feed/namespace.js");
 //# sourceMappingURL=index.js.map

package/src/interfaces/index.js

@@ -1,17 +1,26 @@
 "use strict";
 
+var __createBinding = void 0 && (void 0).__createBinding || (Object.create ? function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  var desc = Object.getOwnPropertyDescriptor(m, k);
+  if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+    desc = {
+      enumerable: true,
+      get: function () {
+        return m[k];
+      }
+    };
+  }
+  Object.defineProperty(o, k2, desc);
+} : function (o, m, k, k2) {
+  if (k2 === undefined) k2 = k;
+  o[k2] = m[k];
+});
+var __exportStar = void 0 && (void 0).__exportStar || function (m, exports) {
+  for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", {
   value: true
 });
-var _http = require("./http.js");
-Object.keys(_http).forEach(function (key) {
-  if (key === "default" || key === "__esModule") return;
-  if (key in exports && exports[key] === _http[key]) return;
-  Object.defineProperty(exports, key, {
-    enumerable: true,
-    get: function () {
-      return _http[key];
-    }
-  });
-});
+__exportStar(require("./http.js"), exports);
 //# sourceMappingURL=index.js.map

package/src/search/index.d.ts

@@ -0,0 +1,2 @@
+export { SearchNamespace } from "./namespace.js";
+//# sourceMappingURL=index.d.ts.map

package/src/search/index.js

@@ -0,0 +1,14 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SearchNamespace = void 0;
+var namespace_js_1 = /*#__PURE__*/require("./namespace.js");
+Object.defineProperty(exports, "SearchNamespace", {
+  enumerable: true,
+  get: function () {
+    return namespace_js_1.SearchNamespace;
+  }
+});
+//# sourceMappingURL=index.js.map

package/src/search/item.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=item.d.ts.map

package/src/search/item.js

@@ -0,0 +1,6 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+//# sourceMappingURL=item.js.map

package/src/search/namespace.d.ts

@@ -0,0 +1,118 @@
+import type { AllLabels, LabelCategories, UserLabelsResponse, UserSemanticSearchResponse, UserSimilarityResponse, UserTopByLabelResponse } from "@embed-ai/types";
+import type { IHttpClient } from "../interfaces/index.js";
+import type { UserLabelsOptions, UserSemanticSearchOptions, UserSimilarOptions, UserTopByLabelOptions } from "./user.js";
+/**
+ * Users namespace containing all user search operations
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key')
+ *
+ * // Find similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
+ *
+ * // Get top users by label
+ * const topUsers = await client.search.users.getTopByLabel('science_technology')
+ *
+ * // Get labels for users
+ * const labels = await client.search.users.getLabels(['16085', '239'])
+ * ```
+ */
+export declare class UsersNamespace {
+    private http;
+    constructor(http: IHttpClient);
+    /**
+     * Get similar users for a given user ID
+     *
+     * @param userId - The user ID (fid) to find similar users for
+     * @param options - Optional configuration with top_k parameter (default: 25)
+     * @returns Promise<UserSimilarityResponse> - Array of similar users with scores
+     *
+     * @example
+     * ```typescript
+     * const client = getClient("your-api-key")
+     * const similarUsers = await client.search.users.similar("16085", { top_k: 10 })
+     * console.log(similarUsers[0].user_id) // "3"
+     * console.log(similarUsers[0].score) // 0.931880295
+     * ```
+     */
+    similar(userId: string, options?: UserSimilarOptions): Promise<UserSimilarityResponse>;
+    /**
+     * Search for users by semantic query
+     *
+     * @param query - The text query to search for similar users
+     * @param options - Optional configuration with top_k parameter (default: 25)
+     * @returns Promise<UserSemanticSearchResponse> - Array of users matching the query with scores
+     *
+     * @example
+     * ```typescript
+     * const client = getClient("your-api-key")
+     * const users = await client.search.users.byQuery("web3 developers", { top_k: 10 })
+     * console.log(users[0].user_id) // "444746"
+     * console.log(users[0].score) // 0.697465777
+     * ```
+     */
+    byQuery(query: string, options?: UserSemanticSearchOptions): Promise<UserSemanticSearchResponse>;
+    /**
+     * Get top users by AI label
+     *
+     * @param label - The AI label to get top users for
+     * @param options - Optional configuration including top_k (default: 100, max: 1000), minimum_activity_count (default: 10), ratio_min (default: 0.75), conf_min (default: 0.6)
+     * @returns Promise<UserTopByLabelResponse> - Array of top users for the label with scores, counts, and ratios
+     *
+     * @example
+     * ```typescript
+     * const client = getClient("your-api-key")
+     * const topUsers = await client.search.users.getTopByLabel("science_technology", {
+     *   top_k: 50,
+     *   minimum_activity_count: 20,
+     *   ratio_min: 0.8,
+     *   conf_min: 0.7
+     * })
+     * console.log(topUsers[0].user_id) // "520701"
+     * console.log(topUsers[0].score) // 0.9471641778666666
+     * console.log(topUsers[0].count) // 12
+     * console.log(topUsers[0].ratio) // 1
+     * ```
+     */
+    getTopByLabel(label: AllLabels, options?: UserTopByLabelOptions): Promise<UserTopByLabelResponse>;
+    /**
+     * Get AI labels for a list of users
+     *
+     * @param userList - Array of user IDs to get labels for
+     * @param labelCategory - The category of labels to retrieve (default: "all")
+     * @param options - Optional configuration
+     * @returns Promise<UserLabelsResponse> - Array of users with their AI labels
+     *
+     * @example
+     * ```typescript
+     * const client = getClient("your-api-key")
+     * const userLabels = await client.search.users.getLabels(["16085", "239", "3"], "topics")
+     * console.log(userLabels[0].user_id) // "16085"
+     * console.log(userLabels[0].ai_labels.topics[0].label) // "arts_culture"
+     * console.log(userLabels[0].ai_labels.topics[0].score) // 0.023266956986850353
+     * ```
+     */
+    getLabels(userList: Array<string>, labelCategory?: LabelCategories, options?: UserLabelsOptions): Promise<UserLabelsResponse>;
+}
+/**
+ * Search namespace containing all search-related operations
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key')
+ *
+ * // Access user search methods
+ * const similarUsers = await client.search.users.similar('16085')
+ * const searchResults = await client.search.users.byQuery('web3 developers')
+ * ```
+ */
+export declare class SearchNamespace {
+    private http;
+    readonly users: UsersNamespace;
+    constructor(http: IHttpClient);
+}
+//# sourceMappingURL=namespace.d.ts.map

package/src/search/namespace.js

@@ -0,0 +1,137 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.SearchNamespace = exports.UsersNamespace = void 0;
+const user_js_1 = /*#__PURE__*/require("./user.js");
+/**
+ * Users namespace containing all user search operations
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key')
+ *
+ * // Find similar users
+ * const similarUsers = await client.search.users.similar('16085')
+ *
+ * // Search users by query
+ * const users = await client.search.users.byQuery('web3 developers')
+ *
+ * // Get top users by label
+ * const topUsers = await client.search.users.getTopByLabel('science_technology')
+ *
+ * // Get labels for users
+ * const labels = await client.search.users.getLabels(['16085', '239'])
+ * ```
+ */
+class UsersNamespace {
+  http;
+  constructor(http) {
+    this.http = http;
+  }
+  /**
+   * Get similar users for a given user ID
+   *
+   * @param userId - The user ID (fid) to find similar users for
+   * @param options - Optional configuration with top_k parameter (default: 25)
+   * @returns Promise<UserSimilarityResponse> - Array of similar users with scores
+   *
+   * @example
+   * ```typescript
+   * const client = getClient("your-api-key")
+   * const similarUsers = await client.search.users.similar("16085", { top_k: 10 })
+   * console.log(similarUsers[0].user_id) // "3"
+   * console.log(similarUsers[0].score) // 0.931880295
+   * ```
+   */
+  async similar(userId, options) {
+    return (0, user_js_1.similar)(this.http, userId, options);
+  }
+  /**
+   * Search for users by semantic query
+   *
+   * @param query - The text query to search for similar users
+   * @param options - Optional configuration with top_k parameter (default: 25)
+   * @returns Promise<UserSemanticSearchResponse> - Array of users matching the query with scores
+   *
+   * @example
+   * ```typescript
+   * const client = getClient("your-api-key")
+   * const users = await client.search.users.byQuery("web3 developers", { top_k: 10 })
+   * console.log(users[0].user_id) // "444746"
+   * console.log(users[0].score) // 0.697465777
+   * ```
+   */
+  async byQuery(query, options) {
+    return (0, user_js_1.byQuery)(this.http, query, options);
+  }
+  /**
+   * Get top users by AI label
+   *
+   * @param label - The AI label to get top users for
+   * @param options - Optional configuration including top_k (default: 100, max: 1000), minimum_activity_count (default: 10), ratio_min (default: 0.75), conf_min (default: 0.6)
+   * @returns Promise<UserTopByLabelResponse> - Array of top users for the label with scores, counts, and ratios
+   *
+   * @example
+   * ```typescript
+   * const client = getClient("your-api-key")
+   * const topUsers = await client.search.users.getTopByLabel("science_technology", {
+   *   top_k: 50,
+   *   minimum_activity_count: 20,
+   *   ratio_min: 0.8,
+   *   conf_min: 0.7
+   * })
+   * console.log(topUsers[0].user_id) // "520701"
+   * console.log(topUsers[0].score) // 0.9471641778666666
+   * console.log(topUsers[0].count) // 12
+   * console.log(topUsers[0].ratio) // 1
+   * ```
+   */
+  async getTopByLabel(label, options) {
+    return (0, user_js_1.getTopByLabel)(this.http, label, options);
+  }
+  /**
+   * Get AI labels for a list of users
+   *
+   * @param userList - Array of user IDs to get labels for
+   * @param labelCategory - The category of labels to retrieve (default: "all")
+   * @param options - Optional configuration
+   * @returns Promise<UserLabelsResponse> - Array of users with their AI labels
+   *
+   * @example
+   * ```typescript
+   * const client = getClient("your-api-key")
+   * const userLabels = await client.search.users.getLabels(["16085", "239", "3"], "topics")
+   * console.log(userLabels[0].user_id) // "16085"
+   * console.log(userLabels[0].ai_labels.topics[0].label) // "arts_culture"
+   * console.log(userLabels[0].ai_labels.topics[0].score) // 0.023266956986850353
+   * ```
+   */
+  async getLabels(userList, labelCategory = "all", options) {
+    return (0, user_js_1.getLabels)(this.http, userList, labelCategory, options);
+  }
+}
+exports.UsersNamespace = UsersNamespace;
+/**
+ * Search namespace containing all search-related operations
+ *
+ * @example
+ * ```typescript
+ * const client = getClient('your-api-key')
+ *
+ * // Access user search methods
+ * const similarUsers = await client.search.users.similar('16085')
+ * const searchResults = await client.search.users.byQuery('web3 developers')
+ * ```
+ */
+class SearchNamespace {
+  http;
+  users;
+  constructor(http) {
+    this.http = http;
+    this.users = new UsersNamespace(this.http);
+  }
+}
+exports.SearchNamespace = SearchNamespace;
+//# sourceMappingURL=namespace.js.map

package/src/search/user.d.ts

@@ -0,0 +1,80 @@
+import type { AllLabels, LabelCategories, LabelsForUsers, LabelsTopUsers, UserLabelsResponse, UserSemanticSearchResponse, UsersFeedSimilar, UserSimilarityResponse, UsersSemanticSearch, UserTopByLabelResponse } from "@embed-ai/types";
+import type { IHttpClient } from "../interfaces/index.js";
+export type UserSimilarOptions = Omit<UsersFeedSimilar, "user_id">;
+export type UserSemanticSearchOptions = Omit<UsersSemanticSearch, "query">;
+export type UserTopByLabelOptions = Omit<LabelsTopUsers, "label">;
+export type UserLabelsOptions = Omit<LabelsForUsers, "users_list" | "label_category">;
+/**
+ * Get similar users for a given user ID
+ *
+ * @param httpClient - HTTP client instance
+ * @param userId - The user ID (fid) to find similar users for
+ * @param options - Optional configuration with top_k parameter
+ * @returns Promise<UserSimilarityResponse> - Array of similar users with scores
+ *
+ * @example
+ * ```typescript
+ * const similarUsers = await client.search.users.similar("16085", { top_k: 10 })
+ * console.log(similarUsers[0].user_id) // "3"
+ * console.log(similarUsers[0].score) // 0.931880295
+ * ```
+ */
+export declare function similar(httpClient: IHttpClient, userId: string, options?: UserSimilarOptions): Promise<UserSimilarityResponse>;
+/**
+ * Search for users by semantic query
+ *
+ * @param httpClient - HTTP client instance
+ * @param query - The text query to search for similar users
+ * @param options - Optional configuration with top_k parameter
+ * @returns Promise<UserSemanticSearchResponse> - Array of users matching the query with scores
+ *
+ * @example
+ * ```typescript
+ * const users = await client.search.users.byQuery("web3 developers", { top_k: 10 })
+ * console.log(users[0].user_id) // "444746"
+ * console.log(users[0].score) // 0.697465777
+ * ```
+ */
+export declare function byQuery(httpClient: IHttpClient, query: string, options?: UserSemanticSearchOptions): Promise<UserSemanticSearchResponse>;
+/**
+ * Get top users by AI label
+ *
+ * @param httpClient - HTTP client instance
+ * @param label - The AI label to get top users for
+ * @param options - Optional configuration including top_k, minimum_activity_count, ratio_min, conf_min
+ * @returns Promise<UserTopByLabelResponse> - Array of top users for the label with scores, counts, and ratios
+ *
+ * @example
+ * ```typescript
+ * const topUsers = await client.search.users.getTopByLabel("science_technology", {
+ *   top_k: 50,
+ *   minimum_activity_count: 20,
+ *   ratio_min: 0.8,
+ *   conf_min: 0.7
+ * })
+ * console.log(topUsers[0].user_id) // "520701"
+ * console.log(topUsers[0].score) // 0.9471641778666666
+ * console.log(topUsers[0].count) // 12
+ * console.log(topUsers[0].ratio) // 1
+ * ```
+ */
+export declare function getTopByLabel(httpClient: IHttpClient, label: AllLabels, options?: UserTopByLabelOptions): Promise<UserTopByLabelResponse>;
+/**
+ * Get AI labels for a list of users
+ *
+ * @param httpClient - HTTP client instance
+ * @param userList - Array of user IDs to get labels for
+ * @param labelCategory - The category of labels to retrieve (default: "all")
+ * @param options - Optional configuration
+ * @returns Promise<UserLabelsResponse> - Array of users with their AI labels
+ *
+ * @example
+ * ```typescript
+ * const userLabels = await client.search.users.getLabels(["16085", "239", "3"], "topics")
+ * console.log(userLabels[0].user_id) // "16085"
+ * console.log(userLabels[0].ai_labels.topics[0].label) // "arts_culture"
+ * console.log(userLabels[0].ai_labels.topics[0].score) // 0.023266956986850353
+ * ```
+ */
+export declare function getLabels(httpClient: IHttpClient, userList: Array<string>, labelCategory?: LabelCategories, options?: UserLabelsOptions): Promise<UserLabelsResponse>;
+//# sourceMappingURL=user.d.ts.map

package/src/search/user.js

@@ -0,0 +1,124 @@
+"use strict";
+
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.similar = similar;
+exports.byQuery = byQuery;
+exports.getTopByLabel = getTopByLabel;
+exports.getLabels = getLabels;
+/**
+ * Get similar users for a given user ID
+ *
+ * @param httpClient - HTTP client instance
+ * @param userId - The user ID (fid) to find similar users for
+ * @param options - Optional configuration with top_k parameter
+ * @returns Promise<UserSimilarityResponse> - Array of similar users with scores
+ *
+ * @example
+ * ```typescript
+ * const similarUsers = await client.search.users.similar("16085", { top_k: 10 })
+ * console.log(similarUsers[0].user_id) // "3"
+ * console.log(similarUsers[0].score) // 0.931880295
+ * ```
+ */
+async function similar(httpClient, userId, options) {
+  const top_k = options?.top_k ?? 25;
+  const params = {
+    user_id: userId,
+    top_k,
+    ...options
+  };
+  const response = await httpClient.post("/v2/farcaster/users/feed/similar", params);
+  return response.body;
+}
+/**
+ * Search for users by semantic query
+ *
+ * @param httpClient - HTTP client instance
+ * @param query - The text query to search for similar users
+ * @param options - Optional configuration with top_k parameter
+ * @returns Promise<UserSemanticSearchResponse> - Array of users matching the query with scores
+ *
+ * @example
+ * ```typescript
+ * const users = await client.search.users.byQuery("web3 developers", { top_k: 10 })
+ * console.log(users[0].user_id) // "444746"
+ * console.log(users[0].score) // 0.697465777
+ * ```
+ */
+async function byQuery(httpClient, query, options) {
+  const top_k = options?.top_k ?? 25;
+  const params = {
+    query,
+    top_k,
+    ...options
+  };
+  const response = await httpClient.post("/v2/farcaster/users/search/semantic", params);
+  return response.body;
+}
+/**
+ * Get top users by AI label
+ *
+ * @param httpClient - HTTP client instance
+ * @param label - The AI label to get top users for
+ * @param options - Optional configuration including top_k, minimum_activity_count, ratio_min, conf_min
+ * @returns Promise<UserTopByLabelResponse> - Array of top users for the label with scores, counts, and ratios
+ *
+ * @example
+ * ```typescript
+ * const topUsers = await client.search.users.getTopByLabel("science_technology", {
+ *   top_k: 50,
+ *   minimum_activity_count: 20,
+ *   ratio_min: 0.8,
+ *   conf_min: 0.7
+ * })
+ * console.log(topUsers[0].user_id) // "520701"
+ * console.log(topUsers[0].score) // 0.9471641778666666
+ * console.log(topUsers[0].count) // 12
+ * console.log(topUsers[0].ratio) // 1
+ * ```
+ */
+async function getTopByLabel(httpClient, label, options) {
+  const top_k = options?.top_k ?? 100;
+  const minimum_activity_count = options?.minimum_activity_count ?? 10;
+  const ratio_min = options?.ratio_min ?? 0.75;
+  const conf_min = options?.conf_min ?? 0.6;
+  const params = {
+    label,
+    top_k,
+    minimum_activity_count,
+    ratio_min,
+    conf_min,
+    ...options
+  };
+  const response = await httpClient.post("/v2/farcaster/users/labels/top-users", params);
+  return response.body;
+}
+/**
+ * Get AI labels for a list of users
+ *
+ * @param httpClient - HTTP client instance
+ * @param userList - Array of user IDs to get labels for
+ * @param labelCategory - The category of labels to retrieve (default: "all")
+ * @param options - Optional configuration
+ * @returns Promise<UserLabelsResponse> - Array of users with their AI labels
+ *
+ * @example
+ * ```typescript
+ * const userLabels = await client.search.users.getLabels(["16085", "239", "3"], "topics")
+ * console.log(userLabels[0].user_id) // "16085"
+ * console.log(userLabels[0].ai_labels.topics[0].label) // "arts_culture"
+ * console.log(userLabels[0].ai_labels.topics[0].score) // 0.023266956986850353
+ * ```
+ */
+async function getLabels(httpClient, userList, labelCategory = "all", options) {
+  const params = {
+    users_list: userList,
+    label_category: labelCategory,
+    ...options
+  };
+  const response = await httpClient.post("/v2/farcaster/users/labels/for-users", params);
+  return response.body;
+}
+//# sourceMappingURL=user.js.map