@nadohq/mobile-client 0.36.0 → 0.38.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nadohq/mobile-client",
-  "version": "0.36.0",
+  "version": "0.38.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.36.0",
+    "@nadohq/shared": "^0.38.0",
     "axios": "1.16.1"
   },
   "peerDependencies": {
@@ -54,5 +54,5 @@
     "bignumber.js": "11.1.1",
     "viem": "2.52.0"
   },
-  "gitHead": "315e4f23dadefeb2f86f713e423241e81467d4c3"
+  "gitHead": "1a536b7f05b1b042ef257b290cdb8c83f48f4dd0"
 }

package/src/MobileClient.ts

@@ -7,28 +7,38 @@ import {
 import axios, { AxiosInstance, AxiosResponse } from 'axios';
 import {
   mapMobileFeedPage,
+  mapMobileFollowListPage,
+  mapMobileFollowListParamsToServer,
+  mapMobileFollowMutationResult,
   mapMobileNotificationPreferences,
   mapMobileNotificationPreferencesToServer,
+  mapMobileProfilesIncludeToServer,
   mapMobilePublicProfile,
   mapMobileRegisteredWallet,
 } from './dataMappers';
 import {
   buildSignedMobileRequest,
   MobileSignedInner,
+  MobileSignedInnerByType,
   MobileSignedInnerParams,
   MobileSignedRequest,
 } from './signing';
 import {
   GetMobileFeedParams,
+  GetMobileFollowersParams,
+  GetMobileFollowingParams,
   GetMobileNotificationPreferencesParams,
-  GetMobilePublicProfileParams,
+  GetMobileProfilesParams,
   GetMobileRegisteredWalletParams,
   GetMobileUsernameAvailabilityParams,
   MobileFeedPage,
+  MobileFollowListPage,
+  MobileFollowMutationResult,
   MobileNotificationPreferences,
   MobilePublicProfile,
   MobileRegisteredWallet,
   MobileRegisterExpoTokenParams,
+  MobileSetFollowParams,
   MobileSetPrivateModeParams,
   MobileSetUsernameParams,
   MobileSignedRequestParams,
@@ -40,6 +50,7 @@ import { MobileServerFailureError } from './types/MobileServerFailureError';
 import { MobileServerSuccessResponse } from './types/serverBaseTypes';
 import {
   MobileServerExecuteResult,
+  MobileServerExecuteSuccessResponse,
   MobileServerPublicExecuteRequest,
 } from './types/serverExecuteTypes';
 import {
@@ -47,6 +58,7 @@ import {
   MobileServerPublicQuerySuccessResponse,
 } from './types/serverQueryTypes';
 import {
+  MobileServerExecuteRequestType,
   MobileServerPublicQueryRequestByType,
   MobileServerPublicQueryRequestType,
 } from './types/serverRequestTypes';
@@ -78,8 +90,8 @@ export interface MobileClientOpts {
 }
 
 /**
- * Client for the Nado mobile service API: usernames, public profile lookups, the global trade feed, privacy
- * settings, and push notification device/preference management.
+ * Client for the Nado mobile service API: usernames, public profile lookups, the global trade feed, the
+ * follower/following graph, privacy settings, and push notification device/preference management.
  */
 export class MobileClient {
   readonly opts: MobileClientOpts;
@@ -125,22 +137,73 @@ export class MobileClient {
   }
 
   /**
-   * Looks up a subaccount's public profile. Every non-isolated subaccount resolves, with `username` and
-   * `displayName` `null` until a username is claimed. Private Mode does not hide the profile itself, only the
-   * account's activity.
+   * Looks up public profiles, optionally with follower totals and a follow summary. Returns one profile per
+   * requested subaccount, in the requested order, so callers can correlate positionally. Every non-isolated
+   * subaccount resolves, with `username` and `displayName` `null` until a username is claimed. Private Mode
+   * does not hide the profile itself, only the account's activity.
    *
-   * @throws {MobileServerFailureError} With error code `PROFILE_NOT_FOUND` if the subaccount is in the
-   * engine-created isolated namespace, which cannot own a profile.
+   * This is the only profile route, so use it for a single subaccount too. It is unsigned, which means
+   * `include.followSummary.viewAs` is an unauthenticated claim.
+   *
+   * @throws {MobileServerFailureError} With error code `INVALID_PROFILES_REQUEST` if `subaccounts` is empty,
+   * holds duplicates, or exceeds `MOBILE_PROFILES_MAX_BATCH_SIZE` (25), or `PROFILE_NOT_FOUND` if any
+   * requested subaccount — or the follow summary's `viewAs` — is in the engine-created isolated namespace.
+   * One isolated member fails the whole batch rather than being omitted.
+   */
+  async getProfiles(
+    params: GetMobileProfilesParams,
+  ): Promise<MobilePublicProfile[]> {
+    const body: MobileServerPublicQueryRequest<'profiles'> = {
+      type: 'profiles',
+      subaccounts: params.subaccounts.map(subaccountToHex),
+      include: params.include
+        ? mapMobileProfilesIncludeToServer(params.include)
+        : undefined,
+    };
+    const data = await this.publicQuery(body);
+    return data.profiles.map(mapMobilePublicProfile);
+  }
+
+  /**
+   * Fetches a page of the accounts that follow the given Profile.
+   *
+   * Ordering depends on `viewAs`. With it, accounts the Viewer already follows come first, unfamiliar
+   * accounts second, and every row carries an `isFollowing`. Without it, the page is ordered by the listed
+   * relationship alone and no row carries an `isFollowing`. In both cases the newest listed relationship
+   * comes first within a group, with a bytes32 tie-break. The grouping is evaluated per request against the
+   * live graph, so following an account from inside the list moves it between groups on the next page —
+   * deduplicate by subaccount and do not re-sort locally.
+   *
+   * @throws {MobileServerFailureError} With error code `PROFILE_NOT_FOUND` if the viewed Profile or `viewAs`
+   * is isolated, `INVALID_FOLLOW_CURSOR` if the cursor is malformed or was issued for a different `viewAs`,
+   * Profile, or list direction (discard it and restart from the first page), or `INVALID_FOLLOW_LIMIT` if
+   * `limit` is outside 1–50.
+   */
+  async getFollowers(
+    params: GetMobileFollowersParams,
+  ): Promise<MobileFollowListPage> {
+    const body: MobileServerPublicQueryRequest<'followers'> = {
+      type: 'followers',
+      ...mapMobileFollowListParamsToServer(params),
+    };
+    const data = await this.publicQuery(body);
+    return mapMobileFollowListPage(data);
+  }
+
+  /**
+   * Fetches a page of the accounts the given Profile follows. Ordering, cursor rules, and errors match
+   * {@link MobileClient.getFollowers}. When `viewAs` reads its own Following list every row is familiar, so
+   * every `isFollowing` is `true`.
    */
-  async getPublicProfile(
-    params: GetMobilePublicProfileParams,
-  ): Promise<MobilePublicProfile> {
-    const body: MobileServerPublicQueryRequest<'profile'> = {
-      type: 'profile',
-      subaccount: subaccountToHex(params),
+  async getFollowing(
+    params: GetMobileFollowingParams,
+  ): Promise<MobileFollowListPage> {
+    const body: MobileServerPublicQueryRequest<'following'> = {
+      type: 'following',
+      ...mapMobileFollowListParamsToServer(params),
     };
     const data = await this.publicQuery(body);
-    return mapMobilePublicProfile(data.profile);
+    return mapMobileFollowListPage(data);
   }
 
   /**
@@ -314,15 +377,43 @@ export class MobileClient {
     return this.execute(signedRequest);
   }
 
+  /**
+   * Sets whether the signing subaccount follows a Profile. Both directions are idempotent: following again
+   * keeps the original relationship creation time, so it does not move the account in recency order, and
+   * unfollowing a relationship that does not exist succeeds with `isFollowing: false`. Unfollowing deletes
+   * the relationship rather than deactivating it, so a later follow gets a new creation time and moves the
+   * account to the front of recency order.
+   *
+   * Only `isFollowing: true` is checked against the canonical Query DB subaccount index, so unfollowing still
+   * works while that index lags.
+   *
+   * @throws {MobileServerFailureError} With error code `INVALID_FOLLOW_TARGET` if the target is the sender or
+   * either party is isolated, `FOLLOWER_NOT_ELIGIBLE` if the sender is not yet in the canonical Query DB
+   * subaccount index, or `FOLLOWING_NOT_FOUND` if the target is not. Both index errors are transient for an
+   * account that is being recorded, so they are retryable after catch-up — unlike `INVALID_FOLLOW_TARGET`.
+   */
+  async setFollow(
+    params: MobileSetFollowParams,
+  ): Promise<MobileFollowMutationResult> {
+    const signedRequest = await this.getSignedRequest('set_follow', params, {
+      subaccount: subaccountToHex(params.target),
+      is_following: params.isFollowing,
+    });
+    const data = await this.execute(signedRequest);
+    return mapMobileFollowMutationResult(data);
+  }
+
   /*
   Base Fns
    */
 
+  // Returns the request narrowed to `type` so `execute` can infer its response from the request it is given,
+  // instead of being told the type a second time at the call site.
   protected async getSignedRequest<T extends MobileSignedInner['type']>(
     type: T,
     params: MobileSignedRequestParams,
     innerParams: MobileSignedInnerParams<T>,
-  ): Promise<MobileSignedRequest> {
+  ): Promise<MobileSignedRequest<MobileSignedInnerByType<T>>> {
     // Use the linked signer if provided, otherwise use the default signer provided to the client
     const walletClient =
       this.opts.linkedSignerWalletClient ?? this.opts.walletClient;
@@ -331,7 +422,10 @@ export class MobileClient {
       throw new WalletNotProvidedError();
     }
 
-    const inner = { type, ...innerParams } as unknown as MobileSignedInner;
+    const inner = {
+      type,
+      ...innerParams,
+    } as unknown as MobileSignedInnerByType<T>;
     return buildSignedMobileRequest({ ...params, walletClient, inner });
   }
 
@@ -367,9 +461,11 @@ export class MobileClient {
     return response.data as MobileServerSuccessResponse;
   }
 
-  protected async execute(
-    body: MobileSignedRequest,
-  ): Promise<MobileServerSuccessResponse> {
+  // `T` is inferred from the body's `type` rather than declared by the caller, for the same reason
+  // `publicQuery` spells its body out as an intersection: an indexed access is not an inference site.
+  protected async execute<T extends MobileServerExecuteRequestType>(
+    body: MobileSignedRequest & { type: T },
+  ): Promise<MobileServerExecuteSuccessResponse<T>> {
     const response = await this.axiosInstance.post<MobileServerExecuteResult>(
       `${this.opts.url}/mobile/execute`,
       body,
@@ -379,7 +475,7 @@ export class MobileClient {
     this.checkServerStatus(response);
 
     // checkServerStatus catches the failure result and throws the error, so the cast to the success response is acceptable here
-    return response.data as MobileServerSuccessResponse;
+    return response.data as MobileServerExecuteSuccessResponse<T>;
   }
 
   /**

package/src/dataMappers.ts

@@ -1,24 +1,41 @@
+import { subaccountToHex } from '@nadohq/shared';
 import {
+  GetMobileFollowListParams,
   MobileFeedPage,
   MobileFeedTrade,
+  MobileFollowListPage,
+  MobileFollowMutationResult,
+  MobileFollowSummary,
+  MobileIdentitySummary,
   MobileNotificationPreferenceScope,
   MobileNotificationPreferences,
+  MobileProfilesInclude,
   MobilePublicProfile,
   MobileRegisteredWallet,
 } from './types/clientTypes';
+import { MobileServerFollowMutationResponse } from './types/serverExecuteTypes';
 import {
   MobileServerFeedTrade,
+  MobileServerFollowSummary,
+  MobileServerIdentitySummary,
   MobileServerNotificationPreferenceScope,
   MobileServerNotificationPreferences,
   MobileServerProfile,
 } from './types/serverModelTypes';
 import {
   MobileServerFeedResponse,
+  MobileServerFollowListResponse,
   MobileServerRegisteredWalletResponse,
 } from './types/serverQueryTypes';
+import {
+  MobileServerFollowListRequest,
+  MobileServerProfilesInclude,
+} from './types/serverRequestTypes';
 
 /**
- * Maps a server-side public profile (snake_case) to its client-side (camelCase) representation.
+ * Maps a server-side public profile (snake_case) to its client-side (camelCase) representation. The three
+ * include-gated fields stay `undefined` when the backend omitted them, rather than being coerced to `null`
+ * or zero, so callers can tell "not requested" from a real value.
  */
 export function mapMobilePublicProfile(
   server: MobileServerProfile,
@@ -28,6 +45,67 @@ export function mapMobilePublicProfile(
     username: server.username,
     displayName: server.display_name,
     privateMode: server.private_mode,
+    followerCount: server.follower_count,
+    followingCount: server.following_count,
+    followSummary: server.follow_summary
+      ? mapMobileFollowSummary(server.follow_summary)
+      : undefined,
+  };
+}
+
+/**
+ * Maps a server-side identity summary (snake_case) to its client-side (camelCase) representation.
+ */
+function mapMobileIdentitySummary(
+  server: MobileServerIdentitySummary,
+): MobileIdentitySummary {
+  return {
+    subaccount: server.subaccount,
+    username: server.username,
+    displayName: server.display_name,
+    avatarUrl: server.avatar_url,
+  };
+}
+
+/**
+ * Maps a server-side follow summary to its client-side representation.
+ */
+function mapMobileFollowSummary(
+  server: MobileServerFollowSummary,
+): MobileFollowSummary {
+  return {
+    isFollowing: server.is_following,
+    followedByCount: server.followed_by_count,
+    followedBy: server.followed_by.map(mapMobileIdentitySummary),
+  };
+}
+
+/**
+ * Maps a server-side Followers or Following response to a client-side {@link MobileFollowListPage}. Rows
+ * keep `isFollowing` absent when the request named no `viewAs`, rather than defaulting it to `false`.
+ */
+export function mapMobileFollowListPage(
+  server: MobileServerFollowListResponse,
+): MobileFollowListPage {
+  return {
+    accounts: server.accounts.map((account) => ({
+      identity: mapMobileIdentitySummary(account.identity),
+      isFollowing: account.is_following,
+      followerCount: account.follower_count,
+    })),
+    nextCursor: server.next_cursor,
+  };
+}
+
+/**
+ * Maps a server-side follow or unfollow response to its client-side representation.
+ */
+export function mapMobileFollowMutationResult(
+  server: MobileServerFollowMutationResponse,
+): MobileFollowMutationResult {
+  return {
+    isFollowing: server.is_following,
+    followerCount: server.follower_count,
   };
 }
 
@@ -56,6 +134,35 @@ function mapMobileNotificationPreferenceScope(
   return { type: 'product', productId: server.product_id };
 }
 
+/**
+ * Maps client-side profiles includes (camelCase) to the server-side (snake_case) wire shape.
+ */
+export function mapMobileProfilesIncludeToServer(
+  include: MobileProfilesInclude,
+): MobileServerProfilesInclude {
+  return {
+    follow_counts: include.followCounts,
+    follow_summary: include.followSummary
+      ? { view_as: subaccountToHex(include.followSummary.viewAs) }
+      : undefined,
+  };
+}
+
+/**
+ * Maps the client-side params of a Followers or Following page to the server-side wire shape. Both list
+ * directions take identical params and differ only in the `type` the caller dispatches on.
+ */
+export function mapMobileFollowListParamsToServer(
+  params: GetMobileFollowListParams,
+): MobileServerFollowListRequest {
+  return {
+    subaccount: subaccountToHex(params.target),
+    view_as: params.viewAs ? subaccountToHex(params.viewAs) : undefined,
+    cursor: params.cursor,
+    limit: params.limit,
+  };
+}
+
 /**
  * Maps client-side notification preferences (camelCase) to the server-side (snake_case) wire shape.
  */
@@ -86,11 +193,8 @@ function mapMobileNotificationPreferenceScopeToServer(
  */
 function mapMobileFeedTrade(server: MobileServerFeedTrade): MobileFeedTrade {
   return {
+    ...mapMobileIdentitySummary(server),
     orderDigest: server.order_digest,
-    subaccount: server.subaccount,
-    username: server.username,
-    displayName: server.display_name,
-    avatarUrl: server.avatar_url,
     productId: server.product_id,
     quantity: server.quantity,
     notional: server.notional,

package/src/signing/canonicalize.ts

@@ -23,6 +23,12 @@ export function canonicalizeMobileInner(
         locale: inner.locale,
         app_version: inner.app_version,
       };
+    case 'set_follow':
+      return {
+        type: 'set_follow',
+        subaccount: inner.subaccount,
+        is_following: inner.is_following,
+      };
     default: {
       throw new Error(
         `canonicalizeMobileInner: unhandled inner payload type: ${JSON.stringify(inner)}`,

package/src/signing/eip712MethodByType.ts

@@ -10,4 +10,5 @@ export const MOBILE_EIP712_METHOD_BY_TYPE: Record<
   set_username: 'mobile:execute_set_username',
   set_private_mode: 'mobile:execute_set_private_mode',
   register_expo_token: 'mobile:execute_register_expo_token',
+  set_follow: 'mobile:execute_set_follow',
 };

package/src/signing/signing.test.ts

@@ -19,8 +19,8 @@ const FIXED_PRIVATE_KEY =
   '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b786907' as const;
 const FIXED_VERIFYING_ADDR = '0x0000000000000000000000000000000000000001';
 
-// `set_username`, `set_private_mode`, and `register_expo_token` mirror the backend's pinned fixtures in
-// mobile/src/api/types.rs, so a divergence here is a real wire-format break rather than a stale expectation.
+// Every hash here mirrors the backend's pinned fixtures in mobile/src/api/types.rs, so a divergence is a
+// real wire-format break rather than a stale expectation.
 const PINNED_HASHES = {
   set_username:
     '0xb4a55d9eb0be4e5c9457761c0c34c75cf39f7c07bd170700d8dd5e9c7de4a659',
@@ -28,8 +28,16 @@ const PINNED_HASHES = {
     '0x4d12a06234d751e6ddcc01d8f70836bb5b7e207e573641d1efb5aaf2b0f30d10',
   register_expo_token:
     '0x1b9471afc9bde66f9bffd576d3326420e1bade4e16afa3a73ddc65f27155611c',
+  set_follow_true:
+    '0x1ff8529b7c1a0111313eed98536e591555a3bcab51133776ce30c6ef32b559b3',
+  set_follow_false:
+    '0xec9e9e8f32ac4fcf3015f8b7f20c338623ff85db0488703c7fb688519a46e2e5',
 } as const;
 
+// Every follow fixture on the backend targets this subaccount.
+const FIXTURE_TARGET_SUBACCOUNT =
+  '0x1111111111111111111111111111111111111111111111111111111111111111' as const;
+
 describe('[mobile-client]: signing (offline)', () => {
   describe('pinned payload hashes', () => {
     it('set_username', () => {
@@ -61,6 +69,26 @@ describe('[mobile-client]: signing (offline)', () => {
       const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
       expect(hash).toBe(PINNED_HASHES.register_expo_token);
     });
+
+    it('set_follow (follow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        is_following: true,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_true);
+    });
+
+    it('set_follow (unfollow)', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_follow',
+        subaccount: FIXTURE_TARGET_SUBACCOUNT,
+        is_following: false,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_follow_false);
+    });
   });
 
   it('canonicalizes msgpack key order regardless of input key order', () => {
@@ -76,8 +104,8 @@ describe('[mobile-client]: signing (offline)', () => {
   });
 
   it('canonicalizes multi-field key order regardless of input key order', () => {
-    // register_expo_token is the only signed payload with more than one field, so it is where a caller can
-    // actually get the order wrong; canonicalizeMobileInner must rebuild it in the backend's declaration order.
+    // register_expo_token has the most fields of any signed payload, so it is where a caller is most likely
+    // to get the order wrong; canonicalizeMobileInner must rebuild it in the backend's declaration order.
     const outOfOrderInner = {
       app_version: '1.2.3',
       locale: 'en-GB',

package/src/signing/types.ts

@@ -11,6 +11,11 @@ import { MobileNotificationPlatform } from '../types/serverModelTypes';
  * declares its structs — `type` first, then the remaining fields — or the hash won't match and signature
  * verification fails. This type only describes the shape; the authoritative runtime key order is enforced by
  * {@link canonicalizeMobileInner}, which is the source of truth. Keep the field order here in sync with it.
+ *
+ * Every bytes32 field must be lowercase hex. The backend decodes them case-insensitively but hashes its own
+ * re-serialization, which is always lowercase, so a mixed-case value is accepted on the wire and then fails
+ * authentication against a hash the client never reproduced. Build them with `subaccountToHex`, which
+ * lowercases; unlike bytes32, string fields such as `display_name` are hashed as-is and keep their casing.
  */
 export type MobileSignedInner =
   | { type: 'set_username'; display_name: string }
@@ -23,14 +28,26 @@ export type MobileSignedInner =
       // backend, which serializes `Option::None` as nil under the same key.
       locale: string | null;
       app_version: string | null;
+    }
+  | {
+      type: 'set_follow';
+      subaccount: Hex;
+      /** `true` follows the target, `false` unfollows it. Both directions are idempotent. */
+      is_following: boolean;
     };
 
+/**
+ * The single {@link MobileSignedInner} member carrying the given `type` tag.
+ */
+export type MobileSignedInnerByType<T extends MobileSignedInner['type']> =
+  Extract<MobileSignedInner, { type: T }>;
+
 /**
  * Type-specific payload fields for a signed inner request of a given `type` (the inner payload without its
  * `type` tag). Derived from {@link MobileSignedInner} so the two never drift apart.
  */
 export type MobileSignedInnerParams<T extends MobileSignedInner['type']> = Omit<
-  Extract<MobileSignedInner, { type: T }>,
+  MobileSignedInnerByType<T>,
   'type'
 >;