@nadohq/mobile-client 0.57.0 → 0.59.0

package/dist/utils/profileSearch.d.ts

@@ -0,0 +1,2 @@
+import { n as MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE, t as MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE } from "../profileSearch-DCuB-IKD.js";
+export { MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE, MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE };

package/dist/utils/profileSearch.js

@@ -0,0 +1,15 @@
+//#region src/utils/profileSearch.ts
+/**
+* Maximum profile search page size without an `include`. Requests outside 1-50 fail with
+* `INVALID_PROFILE_SEARCH_REQUEST`.
+*/
+const MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE = 50;
+/**
+* Maximum profile search page size when `include` asks for follow data, matching
+* `MOBILE_PROFILES_MAX_BATCH_SIZE`. Requests outside 1-25 fail with `INVALID_PROFILE_SEARCH_REQUEST`.
+*/
+const MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE = 25;
+//#endregion
+export { MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE, MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE };
+
+//# sourceMappingURL=profileSearch.js.map

package/dist/utils/profileSearch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profileSearch.js","names":[],"sources":["../../src/utils/profileSearch.ts"],"sourcesContent":["/**\n * Maximum profile search page size without an `include`. Requests outside 1-50 fail with\n * `INVALID_PROFILE_SEARCH_REQUEST`.\n */\nexport const MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE = 50;\n\n/**\n * Maximum profile search page size when `include` asks for follow data, matching\n * `MOBILE_PROFILES_MAX_BATCH_SIZE`. Requests outside 1-25 fail with `INVALID_PROFILE_SEARCH_REQUEST`.\n */\nexport const MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE = 25;\n"],"mappings":";;;;;AAIA,MAAa,sCAAsC;;;;;AAMnD,MAAa,+CAA+C"}

package/dist/utils/serverResponseGuards.d.cts

@@ -1,2 +1,2 @@
-import { n as isMobileServerSuccessResponse, t as isMobileServerFailureResponse } from "../serverResponseGuards-DGhrUL_c.cjs";
+import { n as isMobileServerSuccessResponse, t as isMobileServerFailureResponse } from "../serverResponseGuards-Dkdok0Sm.cjs";
 export { isMobileServerFailureResponse, isMobileServerSuccessResponse };

package/dist/utils/serverResponseGuards.d.ts

@@ -1,2 +1,2 @@
-import { n as isMobileServerSuccessResponse, t as isMobileServerFailureResponse } from "../serverResponseGuards-BGHTBbtz.js";
+import { n as isMobileServerSuccessResponse, t as isMobileServerFailureResponse } from "../serverResponseGuards-BU1Xv_tG.js";
 export { isMobileServerFailureResponse, isMobileServerSuccessResponse };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadohq/mobile-client",
-  "version": "0.57.0",
+  "version": "0.59.0",
   "type": "module",
   "sideEffects": false,
   "description": "HTTP client for the Nado mobile service API — username claims, profiles, privacy settings, and push notification devices & preferences",
@@ -42,7 +42,7 @@
   "types": "./dist/index.d.ts",
   "dependencies": {
     "@msgpack/msgpack": "3.1.3",
-    "@nadohq/shared": "^0.57.0",
+    "@nadohq/shared": "^0.59.0",
     "axios": "1.16.1"
   },
   "peerDependencies": {
@@ -54,5 +54,5 @@
     "bignumber.js": "11.1.1",
     "viem": "2.52.0"
   },
-  "gitHead": "7cb8102ccb2b3632cad3a8c44c3bbe6c7a081ae6"
+  "gitHead": "48af19e135f200eb240e406fdbdb26632970492b"
 }

package/src/MobileClient.ts

@@ -10,11 +10,14 @@ import {
   mapMobileAvatarSelectionToServer,
   mapMobileAvatarUpload,
   mapMobileFeedPage,
+  mapMobileFollowBatchResult,
   mapMobileFollowListPage,
   mapMobileFollowListParamsToServer,
   mapMobileFollowMutationResult,
   mapMobileNotificationPreferences,
   mapMobileNotificationPreferencesToServer,
+  mapMobileProfileSearchPage,
+  mapMobileProfileSearchParamsToServer,
   mapMobileProfilesIncludeToServer,
   mapMobilePublicProfile,
   mapMobileRegisteredWallet,
@@ -53,14 +56,17 @@ import {
   MobileAvatarUpload,
   MobileCreateAvatarUploadParams,
   MobileFeedPage,
+  MobileFollowBatchResultItem,
   MobileFollowListPage,
   MobileFollowMutationResult,
   MobileNotificationPreferences,
+  MobileProfileSearchPage,
   MobilePublicProfile,
   MobileRegisteredWallet,
   MobileRegisterExpoTokenParams,
   MobileSetAvatarParams,
   MobileSetBioParams,
+  MobileSetFollowBatchParams,
   MobileSetFollowParams,
   MobileSetPrivateModeParams,
   MobileSetUsernameParams,
@@ -73,6 +79,7 @@ import {
   MobileUnregisterExpoTokenParams,
   MobileUpdateNotificationPreferencesParams,
   MobileUsernameAvailability,
+  SearchMobileProfilesParams,
 } from './types/clientTypes';
 import { MobileServerFailureError } from './types/MobileServerFailureError';
 import { MobileServerSuccessResponse } from './types/serverBaseTypes';
@@ -206,6 +213,33 @@ export class MobileClient {
     return data.profiles.map(mapMobilePublicProfile);
   }
 
+  /**
+   * Searches claimed profiles by the start of their username, in ascending username order with an exact
+   * match first. Only current claimed identities match: an unnamed profile never does, and Private Mode does
+   * not hide one. Takes the same `include` as {@link MobileClient.getProfiles}, so a page can carry follower
+   * totals and a follow summary without a second request; as there, `include.followSummary.viewAs` is an
+   * unauthenticated claim on an unsigned route.
+   *
+   * Pagination is live rather than snapshot, so deduplicate matches by subaccount across pages. A cursor is
+   * bound to the query alone, so `include` and `limit` may change between pages.
+   *
+   * @throws {MobileServerFailureError} With error code `INVALID_PROFILE_SEARCH_REQUEST` if `query` is outside
+   * the username alphabet or length or `limit` is out of range (1-50, or 1-25 with an include),
+   * `INVALID_PROFILE_SEARCH_CURSOR` if the cursor is malformed or was issued for a different query (discard
+   * it and restart from the first page), or `PROFILE_NOT_FOUND` if `include.followSummary.viewAs` is in the
+   * engine-created isolated namespace.
+   */
+  async searchProfiles(
+    params: SearchMobileProfilesParams,
+  ): Promise<MobileProfileSearchPage> {
+    const body: MobileServerPublicQueryRequest<'search_profiles'> = {
+      type: 'search_profiles',
+      ...mapMobileProfileSearchParamsToServer(params),
+    };
+    const data = await this.publicQuery(body);
+    return mapMobileProfileSearchPage(data);
+  }
+
   /**
    * Fetches a page of the accounts that follow the given Profile.
    *
@@ -675,6 +709,37 @@ export class MobileClient {
     return mapMobileFollowMutationResult(data);
   }
 
+  /**
+   * Sets whether the signing subaccount follows each of up to `MOBILE_FOLLOW_BATCH_MAX_SIZE` (25) Profiles in
+   * one signed request, which costs far less of the shared IP rate limit than one {@link MobileClient.setFollow}
+   * per target. The server validates the whole list before writing and commits every target in one database
+   * transaction, so the batch either fully applies or changes nothing. Each target has the same idempotent
+   * semantics as `setFollow`, so resending a batch is safe.
+   *
+   * Targets are lowercased before signing but not deduplicated, and two spellings of one subaccount are a
+   * duplicate. Longer lists must be split by the caller; each request commits on its own, so earlier chunks
+   * stay applied when a later one fails.
+   *
+   * @returns One result per target, in request order, carrying each target's post-commit follower count.
+   * @throws {MobileServerFailureError} With error code `INVALID_FOLLOW_BATCH` if `targets` is empty, holds
+   * duplicates, or exceeds the maximum, or `INVALID_FOLLOW_TARGET` if any target is the sender or either party
+   * is isolated. Either rejects the whole batch before any write, so do not retry it unchanged.
+   */
+  async setFollowBatch(
+    params: MobileSetFollowBatchParams,
+  ): Promise<MobileFollowBatchResultItem[]> {
+    const signedRequest = await this.getSignedRequest(
+      'set_follow_batch',
+      params,
+      {
+        subaccounts: params.targets.map(subaccountToHex),
+        is_following: params.isFollowing,
+      },
+    );
+    const data = await this.execute(signedRequest);
+    return mapMobileFollowBatchResult(data);
+  }
+
   /*
   Base Fns
    */

package/src/dataMappers.ts

@@ -6,12 +6,14 @@ import {
   MobileAvatarUpload,
   MobileFeedPage,
   MobileFeedTrade,
+  MobileFollowBatchResultItem,
   MobileFollowListPage,
   MobileFollowMutationResult,
   MobileFollowSummary,
   MobileIdentitySummary,
   MobileNotificationPreferenceScope,
   MobileNotificationPreferences,
+  MobileProfileSearchPage,
   MobileProfilesInclude,
   MobilePublicProfile,
   MobileRegisteredWallet,
@@ -36,9 +38,11 @@ import {
   MobileSocialFeedTradeRowBase,
   MobileSocialFeedTraderBadge,
   MobileSocialFeedUpdates,
+  SearchMobileProfilesParams,
 } from './types/clientTypes';
 import {
   MobileServerAvatarUploadResponse,
+  MobileServerFollowBatchResponse,
   MobileServerFollowMutationResponse,
 } from './types/serverExecuteTypes';
 import {
@@ -69,6 +73,7 @@ import {
   MobileServerFeedResponse,
   MobileServerFollowListResponse,
   MobileServerRegisteredWalletResponse,
+  MobileServerSearchProfilesResponse,
   MobileServerSocialFeedItemResponse,
   MobileServerSocialFeedRankedResponse,
   MobileServerSocialFeedResponse,
@@ -78,6 +83,7 @@ import {
 import {
   MobileServerFollowListRequest,
   MobileServerProfilesInclude,
+  MobileServerSearchProfilesRequest,
   MobileServerSocialFeedListParams,
   MobileServerSocialFeedReadParams,
 } from './types/serverRequestTypes';
@@ -184,6 +190,19 @@ export function mapMobileFollowListPage(
   };
 }
 
+/**
+ * Maps a server-side profile search page (snake_case) to its client-side (camelCase) representation. Each
+ * match goes through {@link mapMobilePublicProfile}, so include-gated fields stay `undefined` when omitted.
+ */
+export function mapMobileProfileSearchPage(
+  server: MobileServerSearchProfilesResponse,
+): MobileProfileSearchPage {
+  return {
+    profiles: server.profiles.map(mapMobilePublicProfile),
+    nextCursor: server.next_cursor,
+  };
+}
+
 /**
  * Maps a server-side follow or unfollow response to its client-side representation.
  */
@@ -196,6 +215,19 @@ export function mapMobileFollowMutationResult(
   };
 }
 
+/**
+ * Maps a server-side batch follow or unfollow response to its client-side representation.
+ */
+export function mapMobileFollowBatchResult(
+  server: MobileServerFollowBatchResponse,
+): MobileFollowBatchResultItem[] {
+  return server.results.map((result) => ({
+    subaccount: result.subaccount,
+    isFollowing: result.is_following,
+    followerCount: result.follower_count,
+  }));
+}
+
 /**
  * Maps server-side notification preferences (snake_case) to their client-side (camelCase) representation.
  */
@@ -250,6 +282,22 @@ export function mapMobileFollowListParamsToServer(
   };
 }
 
+/**
+ * Maps the client-side params of a profile search page to the server-side wire shape.
+ */
+export function mapMobileProfileSearchParamsToServer(
+  params: SearchMobileProfilesParams,
+): MobileServerSearchProfilesRequest {
+  return {
+    query: params.query,
+    include: params.include
+      ? mapMobileProfilesIncludeToServer(params.include)
+      : undefined,
+    cursor: params.cursor,
+    limit: params.limit,
+  };
+}
+
 /**
  * Maps client-side notification preferences (camelCase) to the server-side (snake_case) wire shape.
  */

package/src/signing/canonicalize.ts

@@ -49,6 +49,12 @@ export function canonicalizeMobileInner(
         subaccount: inner.subaccount,
         is_following: inner.is_following,
       };
+    case 'set_follow_batch':
+      return {
+        type: 'set_follow_batch',
+        subaccounts: [...inner.subaccounts],
+        is_following: inner.is_following,
+      };
     default: {
       throw new Error(
         `canonicalizeMobileInner: unhandled inner payload type: ${JSON.stringify(inner)}`,

package/src/signing/eip712MethodByType.ts

@@ -14,4 +14,5 @@ export const MOBILE_EIP712_METHOD_BY_TYPE: Record<
   set_private_mode: 'mobile:execute_set_private_mode',
   register_expo_token: 'mobile:execute_register_expo_token',
   set_follow: 'mobile:execute_set_follow',
+  set_follow_batch: 'mobile:execute_set_follow_batch',
 };

package/src/signing/signing.test.ts

@@ -41,12 +41,20 @@ const PINNED_HASHES = {
     '0x1ff8529b7c1a0111313eed98536e591555a3bcab51133776ce30c6ef32b559b3',
   set_follow_false:
     '0xec9e9e8f32ac4fcf3015f8b7f20c338623ff85db0488703c7fb688519a46e2e5',
+  set_follow_batch_true:
+    '0x0d86ef133ad5db8968911d102c48599691dcc40094ace985484c3f7e2cb3a87d',
+  set_follow_batch_false:
+    '0x02272ef5f6c7f9b315a892240af614f9cbbcb1edc69538db37ae1409549ff2fa',
 } as const;
 
 // Every follow fixture on the backend targets this subaccount.
 const FIXTURE_TARGET_SUBACCOUNT =
   '0x1111111111111111111111111111111111111111111111111111111111111111' as const;
 
+// Batch follow fixtures target the subaccount above, then this one.
+const FIXTURE_SECOND_TARGET_SUBACCOUNT =
+  '0x2222222222222222222222222222222222222222222222222222222222222222' as const;
+
 describe('[mobile-client]: signing (offline)', () => {
   describe('pinned payload hashes', () => {
     it('set_bio', () => {
@@ -145,6 +153,32 @@ describe('[mobile-client]: signing (offline)', () => {
       const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
       expect(hash).toBe(PINNED_HASHES.set_follow_false);
     });
+
+    it('set_follow_batch (follow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow_batch',
+        subaccounts: [
+          FIXTURE_TARGET_SUBACCOUNT,
+          FIXTURE_SECOND_TARGET_SUBACCOUNT,
+        ],
+        is_following: true,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_batch_true);
+    });
+
+    it('set_follow_batch (unfollow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow_batch',
+        subaccounts: [
+          FIXTURE_TARGET_SUBACCOUNT,
+          FIXTURE_SECOND_TARGET_SUBACCOUNT,
+        ],
+        is_following: false,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_batch_false);
+    });
   });
 
   it('canonicalizes nested avatar fields before hashing', () => {

package/src/signing/types.ts

@@ -43,6 +43,13 @@ export type MobileSignedInner =
       subaccount: Hex;
       /** `true` follows the target, `false` unfollows it. Both directions are idempotent. */
       is_following: boolean;
+    }
+  | {
+      type: 'set_follow_batch';
+      /** Distinct targets in request order; the response keeps this order. */
+      subaccounts: Hex[];
+      /** `true` follows every target, `false` unfollows every target. Both directions are idempotent. */
+      is_following: boolean;
     };
 
 /**

package/src/types/clientTypes.ts

@@ -149,6 +149,18 @@ export interface MobileFollowListPage {
   nextCursor: string | null;
 }
 
+/**
+ * A page of profiles whose username starts with the searched prefix. Pagination is live rather than snapshot:
+ * a claim or rename between pages can surface a profile twice or skip it, so deduplicate by
+ * {@link MobilePublicProfile.subaccount} and restart from `cursor: undefined` on refresh.
+ */
+export interface MobileProfileSearchPage {
+  /** Matches in ascending bytewise username order, with an exact match ahead of longer ones. */
+  profiles: MobilePublicProfile[];
+  /** `null` means there are no further matches. */
+  nextCursor: string | null;
+}
+
 /**
  * Post-commit state of a follow or unfollow. The mutation and its count share one database transaction, so
  * these values are authoritative — apply them rather than re-reading.
@@ -159,6 +171,18 @@ export interface MobileFollowMutationResult {
   followerCount: number;
 }
 
+/**
+ * Post-commit state of one target in a batch follow or unfollow. The whole batch commits in one database
+ * transaction, so these values are authoritative — apply them rather than re-reading.
+ */
+export interface MobileFollowBatchResultItem {
+  /** The requested target, as lowercase hex. */
+  subaccount: Hex;
+  isFollowing: boolean;
+  /** The *target's* follower count after the batch, not the sender's. */
+  followerCount: number;
+}
+
 /**
  * Result of a username availability check.
  */
@@ -312,6 +336,33 @@ export interface GetMobileProfilesParams {
   include?: MobileProfilesInclude;
 }
 
+/**
+ * Params for {@link MobileClient.searchProfiles}.
+ */
+export interface SearchMobileProfilesParams {
+  /**
+   * Username prefix to match, 1-20 ASCII characters matching `MOBILE_PROFILE_SEARCH_QUERY_PATTERN`: a letter
+   * or digit first, then letters, digits, `_` or `.`. Letters match case-insensitively; whitespace is not
+   * trimmed, so normalize the input before sending it.
+   */
+  query: string;
+  /** Same opt-in extras as {@link GetMobileProfilesParams.include}, applied to every match on the page. */
+  include?: MobileProfilesInclude;
+  /**
+   * Opaque cursor from the previous page's {@link MobileProfileSearchPage.nextCursor}. Omit for the first
+   * page. A cursor is bound to its normalized query but not to `include` or `limit`, so an enriched page
+   * can continue an unenriched search; one issued for another query fails with
+   * `INVALID_PROFILE_SEARCH_CURSOR`.
+   */
+  cursor?: string;
+  /**
+   * Page size, 1-`MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE` (50), or
+   * 1-`MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE` (25) when `include` asks for follow data; the backend
+   * defaults to 25 when omitted.
+   */
+  limit?: number;
+}
+
 /**
  * Params for {@link MobileClient.getFeed}.
  */
@@ -380,6 +431,20 @@ export interface MobileSetFollowParams extends MobileSignedRequestParams {
   isFollowing: boolean;
 }
 
+/**
+ * Params for {@link MobileClient.setFollowBatch}. The subaccount carried by {@link MobileSignedRequestParams}
+ * is the signing Follower; `targets` are the Profiles on the other end of each relationship.
+ */
+export interface MobileSetFollowBatchParams extends MobileSignedRequestParams {
+  /**
+   * 1 to `MOBILE_FOLLOW_BATCH_MAX_SIZE` (25) distinct Profiles, none of them the signing subaccount or an
+   * isolated subaccount. The results keep this order.
+   */
+  targets: Subaccount[];
+  /** `true` follows every target, `false` unfollows every target. Both directions are idempotent. */
+  isFollowing: boolean;
+}
+
 /**
  * Common params for a Followers or Following page.
  */

package/src/types/mobileErrorCodes.ts

@@ -15,6 +15,16 @@ export const MOBILE_ERROR_CODES = {
   PROFILE_NOT_FOUND: 6106,
   /** Profiles lookup is empty, holds duplicates, or exceeds the batch maximum. Do not retry unchanged. */
   INVALID_PROFILES_REQUEST: 6107,
+  /**
+   * Profile search query is outside the username alphabet or length, or its limit is out of range. Do not
+   * retry unchanged.
+   */
+  INVALID_PROFILE_SEARCH_REQUEST: 6108,
+  /**
+   * Profile search cursor is malformed, oversized, or was issued for a different query. Restart from
+   * `cursor: undefined`.
+   */
+  INVALID_PROFILE_SEARCH_CURSOR: 6109,
   /** Follow mutation names the same source and target, or an isolated participant. Do not retry unchanged. */
   INVALID_FOLLOW_TARGET: 6110,
   /** Signed follower is not yet in the canonical Query DB subaccount index. Retry after index catch-up. */
@@ -29,6 +39,8 @@ export const MOBILE_ERROR_CODES = {
   INVALID_BIO: 6115,
   /** Invalid preset, upload size, staging key, or image. Correct the selection before retrying. */
   INVALID_AVATAR: 6116,
+  /** Follow batch is empty, holds duplicates, or exceeds the batch maximum. Do not retry unchanged. */
+  INVALID_FOLLOW_BATCH: 6117,
   INVALID_EXPO_TOKEN: 6200,
   INVALID_DEVICE_METADATA: 6201,
   INVALID_PREFERENCES: 6202,

package/src/types/serverExecuteTypes.ts

@@ -1,3 +1,4 @@
+import { Hex } from 'viem';
 import {
   MobileServerFailureResponse,
   MobileServerSuccessResponse,
@@ -32,6 +33,26 @@ export interface MobileServerFollowMutationResponse {
   follower_count: number;
 }
 
+/**
+ * One target's post-commit state in a `set_follow_batch` response.
+ */
+export interface MobileServerFollowBatchResultItem {
+  /** The requested target, as lowercase hex. */
+  subaccount: Hex;
+  is_following: boolean;
+  /** The *target's* follower count after the batch, not the sender's. */
+  follower_count: number;
+}
+
+/**
+ * Payload the `set_follow_batch` execute returns alongside the success envelope: one result per target, in
+ * request order. Every write and count runs in one database transaction, so the batch either fully applies or
+ * changes nothing, and these values are authoritative post-commit state.
+ */
+export interface MobileServerFollowBatchResponse {
+  results: MobileServerFollowBatchResultItem[];
+}
+
 /**
  * Payload of an execute route that returns nothing beyond the success discriminant. Spelled `Record<never,
  * never>` rather than `Record<string, never>` because the latter's index signature would collapse `status` to
@@ -55,8 +76,8 @@ export interface MobileServerAvatarUploadResponse {
 
 /**
  * Success payloads for each signed `execute`, keyed by request `type`. Most execute routes carry no payload
- * beyond the success discriminant and so map to an empty object; `set_follow` returns its post-commit
- * relationship state, and `create_avatar_upload` returns a temporary upload grant.
+ * beyond the success discriminant and so map to an empty object; `set_follow` and `set_follow_batch` return
+ * their post-commit relationship state, and `create_avatar_upload` returns a temporary upload grant.
  */
 export interface MobileServerExecuteResponseByType {
   /** Bio writes return only the success envelope. */
@@ -69,6 +90,7 @@ export interface MobileServerExecuteResponseByType {
   set_private_mode: MobileServerEmptyExecuteResponse;
   register_expo_token: MobileServerEmptyExecuteResponse;
   set_follow: MobileServerFollowMutationResponse;
+  set_follow_batch: MobileServerFollowBatchResponse;
 }
 
 /**

package/src/types/serverQueryTypes.ts

@@ -55,6 +55,16 @@ export interface MobileServerProfilesResponse {
   profiles: MobileServerProfile[];
 }
 
+/**
+ * Payload of the `search_profiles` public query success response. Matches come in ascending bytewise
+ * username order, an exact match first, and carry the same include-gated fields as a `profiles` entry.
+ */
+export interface MobileServerSearchProfilesResponse {
+  profiles: MobileServerProfile[];
+  /** `null` means there are no further matches. */
+  next_cursor: string | null;
+}
+
 /**
  * Payload of the `followers` and `following` public query success responses. Both list directions share one
  * shape; only the relationship that selected the rows differs.
@@ -177,6 +187,7 @@ export interface MobileServerPublicQueryResponseByType {
   feed_updates: MobileServerSocialFeedUpdatesResponse;
   username_availability: MobileServerUsernameAvailabilityResponse;
   profiles: MobileServerProfilesResponse;
+  search_profiles: MobileServerSearchProfilesResponse;
   followers: MobileServerFollowListResponse;
   following: MobileServerFollowListResponse;
   feed: MobileServerFeedResponse;

package/src/types/serverRequestTypes.ts

@@ -40,6 +40,23 @@ export interface MobileServerFollowListRequest {
   limit?: number;
 }
 
+/**
+ * Params of the `search_profiles` public query.
+ */
+export interface MobileServerSearchProfilesRequest {
+  /**
+   * Username prefix, 1-20 ASCII bytes: a letter or digit first, then letters, digits, `_` or `.`. The
+   * backend lowercases letters and trims nothing.
+   */
+  query: string;
+  /** Same opt-in extras as the `profiles` query, applied to every match on the page. */
+  include?: MobileServerProfilesInclude;
+  /** Opaque keyset cursor from a prior page's `next_cursor`. Omitted requests the first page. */
+  cursor?: string;
+  /** Page size, 1-50, or 1-25 when `include` asks for follow data; the backend defaults to 25 when omitted. */
+  limit?: number;
+}
+
 /** Common filters and pagination for social feed lists. */
 export interface MobileServerSocialFeedListParams {
   /** OR-ed content filters; combined with other filters using AND. */
@@ -144,6 +161,7 @@ export interface MobileServerPublicQueryRequestByType {
     subaccounts: Hex[];
     include?: MobileServerProfilesInclude;
   };
+  search_profiles: MobileServerSearchProfilesRequest;
   followers: MobileServerFollowListRequest;
   following: MobileServerFollowListRequest;
   feed: {

package/src/utils/follow.ts

@@ -20,3 +20,9 @@ export const MOBILE_FOLLOWED_BY_PREVIEW_LIMIT = 2;
  * this many fail with `INVALID_PROFILES_REQUEST`.
  */
 export const MOBILE_PROFILES_MAX_BATCH_SIZE = 25;
+
+/**
+ * Maximum number of targets a single follow batch accepts. An empty list, a duplicate, or more than this many
+ * fail with `INVALID_FOLLOW_BATCH`.
+ */
+export const MOBILE_FOLLOW_BATCH_MAX_SIZE = 25;

package/src/utils/index.ts

@@ -2,4 +2,5 @@ export * from './feed';
 export * from './follow';
 export * from './patterns';
 export * from './profile';
+export * from './profileSearch';
 export * from './serverResponseGuards';

package/src/utils/patterns.ts

@@ -2,3 +2,10 @@
  * Validates a display name: 3-20 ASCII characters from `[A-Za-z0-9_.]`, allowed in any position.
  */
 export const MOBILE_DISPLAY_NAME_PATTERN = /^[A-Za-z0-9_.]{3,20}$/;
+
+/**
+ * Validates a profile search query: 1-20 ASCII characters, a letter or digit first, then letters, digits, `_`
+ * or `.`. The backend lowercases letters and trims nothing, so a prefix shorter than a full username matches.
+ */
+export const MOBILE_PROFILE_SEARCH_QUERY_PATTERN =
+  /^[A-Za-z0-9][A-Za-z0-9_.]{0,19}$/;

package/src/utils/profileSearch.ts

@@ -0,0 +1,11 @@
+/**
+ * Maximum profile search page size without an `include`. Requests outside 1-50 fail with
+ * `INVALID_PROFILE_SEARCH_REQUEST`.
+ */
+export const MOBILE_PROFILE_SEARCH_MAX_PAGE_SIZE = 50;
+
+/**
+ * Maximum profile search page size when `include` asks for follow data, matching
+ * `MOBILE_PROFILES_MAX_BATCH_SIZE`. Requests outside 1-25 fail with `INVALID_PROFILE_SEARCH_REQUEST`.
+ */
+export const MOBILE_PROFILE_SEARCH_MAX_ENRICHED_PAGE_SIZE = 25;