@nadohq/mobile-client 0.27.0

package/src/MobileClient.ts

@@ -0,0 +1,395 @@
+import {
+  WalletClientWithAccount,
+  WalletNotProvidedError,
+} from '@nadohq/shared';
+import axios, { AxiosInstance, AxiosResponse } from 'axios';
+import {
+  mapMobileIdentity,
+  mapMobileNotificationPreferences,
+  mapMobileNotificationPreferencesToServer,
+  mapMobilePublicProfile,
+  mapMobileRegisteredDevice,
+} from './dataMappers';
+import {
+  buildSignedMobileRequest,
+  MobileSignedInner,
+  MobileSignedInnerParams,
+  MobileSignedRequest,
+} from './signing';
+import {
+  GetMobileNotificationPreferencesParams,
+  GetMobilePublicProfileParams,
+  GetMobileRegisteredDevicesParams,
+  GetMobileSelfIdentityParams,
+  GetMobileUsernameAvailabilityParams,
+  MobileClaimUsernameParams,
+  MobileIdentity,
+  MobileNotificationPreferences,
+  MobilePublicProfile,
+  MobileRegisteredDevice,
+  MobileRegisterExpoTokenParams,
+  MobileSetPrivateModeParams,
+  MobileSignedRequestParams,
+  MobileUnregisterExpoTokenParams,
+  MobileUpdateNotificationPreferencesParams,
+  MobileUpdateUsernameParams,
+  MobileUsernameAvailability,
+} from './types/clientTypes';
+import { MobileServerFailureError } from './types/MobileServerFailureError';
+import { MobileServerSuccessResponse } from './types/serverBaseTypes';
+import { MobileServerExecuteResult } from './types/serverExecuteTypes';
+import {
+  MobileServerNotificationPreferencesResponse,
+  MobileServerProfileRequest,
+  MobileServerProfileResponse,
+  MobileServerRegisteredDevicesResponse,
+  MobileServerSelfIdentityResponse,
+  MobileServerUsernameAvailabilityRequest,
+  MobileServerUsernameAvailabilityResponse,
+} from './types/serverQueryTypes';
+import {
+  isMobileServerFailureResponse,
+  isMobileServerSuccessResponse,
+} from './utils/serverResponseGuards';
+
+/**
+ * Options for constructing a {@link MobileClient}.
+ */
+export interface MobileClientOpts {
+  /**
+   * Base URL of the mobile service API, e.g. {@link MOBILE_CLIENT_ENDPOINTS}.
+   */
+  url: string;
+  /**
+   * Wallet client used to sign requests.
+   */
+  walletClient?: WalletClientWithAccount;
+  /**
+   * If provided, this signer is used instead of `walletClient` for all signed requests.
+   */
+  linkedSignerWalletClient?: WalletClientWithAccount;
+}
+
+/**
+ * Client for the Nado mobile service API: username claims, public profile lookups, privacy settings, and
+ * push notification device/preference management.
+ */
+export class MobileClient {
+  readonly opts: MobileClientOpts;
+  readonly axiosInstance: AxiosInstance;
+
+  constructor(opts: MobileClientOpts) {
+    this.opts = opts;
+    this.axiosInstance = axios.create({
+      withCredentials: true,
+      // We have custom logic to validate response status and create an appropriate error
+      validateStatus: () => true,
+    });
+  }
+
+  /**
+   * Sets the linked signer for requests
+   *
+   * @param linkedSignerWalletClient The linkedSigner to use for all signatures. Set to null to revert to the chain signer
+   */
+  public setLinkedSigner(
+    linkedSignerWalletClient: WalletClientWithAccount | null,
+  ) {
+    this.opts.linkedSignerWalletClient = linkedSignerWalletClient ?? undefined;
+  }
+
+  /*
+  Public queries
+   */
+
+  /**
+   * Checks whether a username derived from the given display name is available to claim.
+   */
+  async getUsernameAvailability(
+    params: GetMobileUsernameAvailabilityParams,
+  ): Promise<MobileUsernameAvailability> {
+    const body: MobileServerUsernameAvailabilityRequest = {
+      type: 'username_availability',
+      display_name: params.displayName,
+    };
+    const data =
+      await this.publicQuery<MobileServerUsernameAvailabilityResponse>(body);
+    return { username: data.username, available: data.available };
+  }
+
+  /**
+   * Looks up a subaccount's public profile by username.
+   *
+   * @throws {MobileServerFailureError} With error code `PROFILE_NOT_FOUND` if no identity has claimed the
+   * username or it is invalid. Private Mode does not hide the profile itself, only the account's activity.
+   */
+  async getPublicProfile(
+    params: GetMobilePublicProfileParams,
+  ): Promise<MobilePublicProfile> {
+    const body: MobileServerProfileRequest = {
+      type: 'profile',
+      username: params.username,
+    };
+    const data = await this.publicQuery<MobileServerProfileResponse>(body);
+    return mapMobilePublicProfile(data.profile);
+  }
+
+  /*
+  Signed queries
+   */
+
+  /**
+   * Fetches the caller's own identity for a subaccount. Returns `null` if the subaccount has not claimed a
+   * username yet — this is normal data, not an error.
+   */
+  async getSelfIdentity(
+    params: GetMobileSelfIdentityParams,
+  ): Promise<MobileIdentity | null> {
+    const signedRequest = await this.getSignedRequest(
+      'self_identity',
+      params,
+      {},
+    );
+    const data =
+      await this.query<MobileServerSelfIdentityResponse>(signedRequest);
+    return data.identity ? mapMobileIdentity(data.identity) : null;
+  }
+
+  /**
+   * Fetches a wallet's push notification preferences. Falls back to the backend's defaults if the wallet has
+   * never updated its preferences.
+   */
+  async getNotificationPreferences(
+    params: GetMobileNotificationPreferencesParams,
+  ): Promise<MobileNotificationPreferences> {
+    const signedRequest = await this.getSignedRequest(
+      'notification_preferences',
+      params,
+      {},
+    );
+    const data =
+      await this.query<MobileServerNotificationPreferencesResponse>(
+        signedRequest,
+      );
+    return mapMobileNotificationPreferences(data.preferences);
+  }
+
+  /**
+   * Fetches the devices registered for push notifications for a wallet.
+   */
+  async getRegisteredDevices(
+    params: GetMobileRegisteredDevicesParams,
+  ): Promise<MobileRegisteredDevice[]> {
+    const signedRequest = await this.getSignedRequest(
+      'registered_devices',
+      params,
+      {},
+    );
+    const data =
+      await this.query<MobileServerRegisteredDevicesResponse>(signedRequest);
+    return data.devices.map(mapMobileRegisteredDevice);
+  }
+
+  /*
+  Signed executes
+   */
+
+  /**
+   * Claims a username for a subaccount, derived from the given display name.
+   */
+  async claimUsername(
+    params: MobileClaimUsernameParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'claim_username',
+      params,
+      {
+        display_name: params.displayName,
+      },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /**
+   * Updates the display name for a subaccount's already-claimed identity.
+   */
+  async updateUsername(
+    params: MobileUpdateUsernameParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'update_username',
+      params,
+      { display_name: params.displayName },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /**
+   * Sets whether a subaccount's profile is private.
+   */
+  async setPrivateMode(
+    params: MobileSetPrivateModeParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'set_private_mode',
+      params,
+      { private_mode: params.privateMode },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /**
+   * Registers an Expo push token for the wallet, transferring active ownership of the token if another
+   * wallet had registered it. Idempotent per `(wallet, token)`.
+   *
+   * @throws {MobileServerFailureError} With error code `INVALID_EXPO_TOKEN` if the token is not a valid Expo
+   * push token, or `INVALID_DEVICE_METADATA` if `locale` (max 35 chars) or `appVersion` (max 64 chars) is
+   * too long.
+   */
+  async registerExpoToken(
+    params: MobileRegisterExpoTokenParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'register_expo_token',
+      params,
+      {
+        expo_token: params.expoToken,
+        platform: params.platform,
+        locale: params.locale ?? null,
+        app_version: params.appVersion ?? null,
+      },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /**
+   * Unregisters an Expo push token for the wallet. Idempotent — unregistering an unknown token succeeds.
+   */
+  async unregisterExpoToken(
+    params: MobileUnregisterExpoTokenParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'unregister_expo_token',
+      params,
+      { expo_token: params.expoToken },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /**
+   * Replaces the wallet's push notification preferences. The backend requires `schemaVersion` of 1, exactly
+   * one entry per known category, and empty `scopes` on every entry.
+   *
+   * @throws {MobileServerFailureError} With error code `INVALID_PREFERENCES` if those rules are violated.
+   */
+  async updateNotificationPreferences(
+    params: MobileUpdateNotificationPreferencesParams,
+  ): Promise<MobileServerSuccessResponse> {
+    const signedRequest = await this.getSignedRequest(
+      'update_preferences',
+      params,
+      {
+        preferences: mapMobileNotificationPreferencesToServer(
+          params.preferences,
+        ),
+      },
+    );
+    return this.execute(signedRequest);
+  }
+
+  /*
+  Base Fns
+   */
+
+  protected async getSignedRequest<T extends MobileSignedInner['type']>(
+    type: T,
+    params: MobileSignedRequestParams,
+    innerParams: MobileSignedInnerParams<T>,
+  ): Promise<MobileSignedRequest> {
+    // Use the linked signer if provided, otherwise use the default signer provided to the client
+    const walletClient =
+      this.opts.linkedSignerWalletClient ?? this.opts.walletClient;
+
+    if (walletClient == null) {
+      throw new WalletNotProvidedError();
+    }
+
+    const inner = { type, ...innerParams } as MobileSignedInner;
+    return buildSignedMobileRequest({ ...params, walletClient, inner });
+  }
+
+  protected async publicQuery<TResponse extends { status: 'success' }>(
+    body: object,
+  ): Promise<TResponse> {
+    const response = await this.axiosInstance.post<unknown>(
+      `${this.opts.url}/mobile/public_query`,
+      body,
+    );
+
+    this.checkResponseStatus(response);
+    this.checkServerStatus(response);
+
+    // checkServerStatus throws on failure responses so the cast to the success response is acceptable here
+    return response.data as TResponse;
+  }
+
+  protected async query<TResponse extends { status: 'success' }>(
+    body: MobileSignedRequest,
+  ): Promise<TResponse> {
+    const response = await this.axiosInstance.post<unknown>(
+      `${this.opts.url}/mobile/query`,
+      body,
+    );
+
+    this.checkResponseStatus(response);
+    this.checkServerStatus(response);
+
+    // checkServerStatus throws on failure responses so the cast to the success response is acceptable here
+    return response.data as TResponse;
+  }
+
+  protected async execute(
+    body: MobileSignedRequest,
+  ): Promise<MobileServerSuccessResponse> {
+    const response = await this.axiosInstance.post<MobileServerExecuteResult>(
+      `${this.opts.url}/mobile/execute`,
+      body,
+    );
+
+    this.checkResponseStatus(response);
+    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;
+  }
+
+  /**
+   * Validates the HTTP status before interpreting the body. Unlike the engine, the mobile backend returns
+   * failure envelopes with non-2xx statuses (e.g. 404 for `PROFILE_NOT_FOUND`), so a non-2xx response with a
+   * failure envelope still throws the typed error; anything else is a transport-level error.
+   */
+  private checkResponseStatus(response: AxiosResponse<unknown>) {
+    if (response.status >= 200 && response.status < 300) {
+      return;
+    }
+    if (isMobileServerFailureResponse(response.data)) {
+      throw new MobileServerFailureError(response.data, response.status);
+    }
+    throw new Error(
+      `Unexpected response from mobile service: ${response.status} ${response.statusText}. Data: ${JSON.stringify(response.data)}`,
+    );
+  }
+
+  private checkServerStatus(response: AxiosResponse<unknown>) {
+    const { data } = response;
+
+    if (isMobileServerFailureResponse(data)) {
+      throw new MobileServerFailureError(data, response.status);
+    }
+    if (!isMobileServerSuccessResponse(data)) {
+      throw new Error(
+        `Unexpected response from mobile service: missing success envelope. Data: ${JSON.stringify(data)}`,
+      );
+    }
+  }
+}

package/src/dataMappers.ts

@@ -0,0 +1,106 @@
+import {
+  MobileIdentity,
+  MobileNotificationPreferenceScope,
+  MobileNotificationPreferences,
+  MobilePublicProfile,
+  MobileRegisteredDevice,
+} from './types/clientTypes';
+import {
+  MobileServerIdentity,
+  MobileServerNotificationPreferenceScope,
+  MobileServerNotificationPreferences,
+  MobileServerProfile,
+  MobileServerRegisteredDevice,
+} from './types/serverModelTypes';
+
+/**
+ * Maps a server-side identity (snake_case) to its client-side (camelCase) representation.
+ */
+export function mapMobileIdentity(
+  server: MobileServerIdentity,
+): MobileIdentity {
+  return {
+    subaccount: server.subaccount,
+    username: server.username,
+    displayName: server.display_name,
+    privateMode: server.private_mode,
+  };
+}
+
+/**
+ * Maps a server-side public profile (snake_case) to its client-side (camelCase) representation.
+ */
+export function mapMobilePublicProfile(
+  server: MobileServerProfile,
+): MobilePublicProfile {
+  return {
+    subaccount: server.subaccount,
+    username: server.username,
+    displayName: server.display_name,
+  };
+}
+
+/**
+ * Maps server-side notification preferences (snake_case) to their client-side (camelCase) representation.
+ */
+export function mapMobileNotificationPreferences(
+  server: MobileServerNotificationPreferences,
+): MobileNotificationPreferences {
+  return {
+    schemaVersion: server.schema_version,
+    categories: server.categories.map((category) => ({
+      category: category.category,
+      enabled: category.enabled,
+      scopes: category.scopes.map(mapMobileNotificationPreferenceScope),
+    })),
+  };
+}
+
+function mapMobileNotificationPreferenceScope(
+  server: MobileServerNotificationPreferenceScope,
+): MobileNotificationPreferenceScope {
+  if (server.type === 'subaccount') {
+    return { type: 'subaccount', subaccount: server.subaccount };
+  }
+  return { type: 'product', productId: server.product_id };
+}
+
+/**
+ * Maps client-side notification preferences (camelCase) to the server-side (snake_case) wire shape.
+ */
+export function mapMobileNotificationPreferencesToServer(
+  preferences: MobileNotificationPreferences,
+): MobileServerNotificationPreferences {
+  return {
+    schema_version: preferences.schemaVersion,
+    categories: preferences.categories.map((category) => ({
+      category: category.category,
+      enabled: category.enabled,
+      scopes: category.scopes.map(mapMobileNotificationPreferenceScopeToServer),
+    })),
+  };
+}
+
+function mapMobileNotificationPreferenceScopeToServer(
+  scope: MobileNotificationPreferenceScope,
+): MobileServerNotificationPreferenceScope {
+  if (scope.type === 'subaccount') {
+    return { type: 'subaccount', subaccount: scope.subaccount };
+  }
+  return { type: 'product', product_id: scope.productId };
+}
+
+/**
+ * Maps a server-side registered device (snake_case) to its client-side (camelCase) representation.
+ */
+export function mapMobileRegisteredDevice(
+  server: MobileServerRegisteredDevice,
+): MobileRegisteredDevice {
+  return {
+    platform: server.platform,
+    locale: server.locale,
+    appVersion: server.app_version,
+    tokenFingerprintPrefix: server.token_fingerprint_prefix,
+    lastSeenAt: server.last_seen_at,
+  };
+}

package/src/endpoints.ts

@@ -0,0 +1,10 @@
+import { ChainEnv } from '@nadohq/shared';
+
+/**
+ * Base URLs for the Nado mobile service API, keyed by chain environment.
+ */
+export const MOBILE_CLIENT_ENDPOINTS: Record<ChainEnv, string> = {
+  local: 'http://mobile.local.nado.xyz:8004/v1',
+  inkTestnet: 'https://mobile.test.nado.xyz/v1',
+  inkMainnet: 'https://mobile.prod.nado.xyz/v1',
+};

package/src/index.ts

@@ -0,0 +1,5 @@
+export * from './endpoints';
+export * from './MobileClient';
+export * from './signing';
+export * from './types';
+export * from './utils';

package/src/signing/buildSignedMobileRequest.ts

@@ -0,0 +1,58 @@
+import { getSignedTransactionRequest, subaccountToHex } from '@nadohq/shared';
+import { canonicalizeMobileInner } from './canonicalize';
+import { MOBILE_EIP712_METHOD_BY_TYPE } from './eip712MethodByType';
+import { getMobileNonce } from './nonce';
+import { getMobilePayloadHash } from './payloadHash';
+import {
+  BuildSignedMobileRequestParams,
+  MobileSignedInner,
+  MobileSignedRequest,
+} from './types';
+
+/**
+ * Builds and signs a mobile service API request: canonicalizes the inner payload, derives `sender` from the
+ * subaccount owner (never the signer), computes the EIP-712 `payloadHash`, signs the `NadoAuthentication`
+ * typed data, and returns the flattened signed body ready to POST.
+ */
+export async function buildSignedMobileRequest<T extends MobileSignedInner>(
+  params: BuildSignedMobileRequestParams & { inner: T },
+): Promise<MobileSignedRequest<T>> {
+  const {
+    walletClient,
+    subaccountOwner,
+    subaccountName,
+    chainId,
+    verifyingAddr,
+    inner,
+  } = params;
+
+  const canonicalInner = canonicalizeMobileInner(inner) as T;
+  const sender = subaccountToHex({
+    subaccountOwner,
+    subaccountName,
+  });
+  const payloadHash = getMobilePayloadHash(canonicalInner);
+  const nonce = params.nonce ?? getMobileNonce();
+  const method = MOBILE_EIP712_METHOD_BY_TYPE[canonicalInner.type];
+
+  const signature = await getSignedTransactionRequest({
+    requestType: 'nado_authentication',
+    requestParams: {
+      method,
+      subaccountOwner,
+      subaccountName,
+      payloadHash,
+      nonce: nonce.toString(),
+    },
+    chainId,
+    verifyingContract: verifyingAddr,
+    walletClient,
+  });
+
+  return {
+    ...canonicalInner,
+    signature,
+    sender,
+    nonce: nonce.toString(),
+  };
+}

package/src/signing/canonicalize.ts

@@ -0,0 +1,69 @@
+import { MobileServerNotificationPreferences } from '../types/serverModelTypes';
+import { MobileSignedInner } from './types';
+
+/**
+ * Rebuilds an inner payload with its keys in the backend's struct declaration order (`type` first, then the
+ * remaining fields in the exact order the backend serializes them). msgpack encodes object keys in insertion
+ * order and the payload hash must be reproducible regardless of how the caller constructed the object, so
+ * every inner payload — and each of its sub-types — is canonicalized here before hashing. This function (with
+ * {@link canonicalizeNotificationPreferences} for nested preferences) is the source of truth for that order.
+ */
+export function canonicalizeMobileInner(
+  inner: MobileSignedInner,
+): MobileSignedInner {
+  switch (inner.type) {
+    case 'claim_username':
+      return { type: 'claim_username', display_name: inner.display_name };
+    case 'update_username':
+      return { type: 'update_username', display_name: inner.display_name };
+    case 'set_private_mode':
+      return { type: 'set_private_mode', private_mode: inner.private_mode };
+    case 'self_identity':
+      return { type: 'self_identity' };
+    case 'register_expo_token':
+      return {
+        type: 'register_expo_token',
+        expo_token: inner.expo_token,
+        platform: inner.platform,
+        locale: inner.locale,
+        app_version: inner.app_version,
+      };
+    case 'unregister_expo_token':
+      return { type: 'unregister_expo_token', expo_token: inner.expo_token };
+    case 'update_preferences':
+      return {
+        type: 'update_preferences',
+        preferences: canonicalizeNotificationPreferences(inner.preferences),
+      };
+    case 'notification_preferences':
+      return { type: 'notification_preferences' };
+    case 'registered_devices':
+      return { type: 'registered_devices' };
+    default: {
+      throw new Error(
+        `canonicalizeMobileInner: unhandled inner payload type: ${JSON.stringify(inner)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Rebuilds notification preferences with keys in the backend's struct declaration order, so the msgpack
+ * encoding matches the backend's `rmp_serde::to_vec_named` output field-for-field.
+ */
+function canonicalizeNotificationPreferences(
+  preferences: MobileServerNotificationPreferences,
+): MobileServerNotificationPreferences {
+  return {
+    schema_version: preferences.schema_version,
+    categories: preferences.categories.map((category) => ({
+      category: category.category,
+      enabled: category.enabled,
+      scopes: category.scopes.map((scope) =>
+        scope.type === 'subaccount'
+          ? { type: 'subaccount', subaccount: scope.subaccount }
+          : { type: 'product', product_id: scope.product_id },
+      ),
+    })),
+  };
+}

package/src/signing/eip712MethodByType.ts

@@ -0,0 +1,19 @@
+import { MobileSignedInner } from './types';
+
+/**
+ * EIP-712 `method` string for each signed inner payload type.
+ */
+export const MOBILE_EIP712_METHOD_BY_TYPE: Record<
+  MobileSignedInner['type'],
+  string
+> = {
+  claim_username: 'mobile:execute_claim_username',
+  update_username: 'mobile:execute_update_username',
+  set_private_mode: 'mobile:execute_set_private_mode',
+  self_identity: 'mobile:query_self_identity',
+  register_expo_token: 'mobile:execute_register_expo_token',
+  unregister_expo_token: 'mobile:execute_unregister_expo_token',
+  update_preferences: 'mobile:execute_update_preferences',
+  notification_preferences: 'mobile:query_notification_preferences',
+  registered_devices: 'mobile:query_registered_devices',
+};

package/src/signing/index.ts

@@ -0,0 +1,6 @@
+export * from './buildSignedMobileRequest';
+export * from './canonicalize';
+export * from './eip712MethodByType';
+export * from './nonce';
+export * from './payloadHash';
+export * from './types';

package/src/signing/nonce.ts

@@ -0,0 +1,16 @@
+/**
+ * Generates a `nonce` for a signed mobile service API request, following the same shape as `getOrderNonce`:
+ * a receive-deadline timestamp in the high digits plus a random low-digits component to avoid collisions. The
+ * server reads `nonce / 1_000_000` as a millisecond receive deadline, which must be later than server time
+ * and no more than 100s ahead — hence the 30s default window. The random low six digits keep nonces
+ * generated within the same millisecond distinct.
+ *
+ * @param deadlineMs - Receive deadline in milliseconds; defaults to 30s ahead of now.
+ * @param randomInt - Random integer in `[0, 1_000_000)` placed in the low six digits to avoid collisions.
+ */
+export function getMobileNonce(
+  deadlineMs: number = Date.now() + 30_000,
+  randomInt: number = Math.floor(Math.random() * 1_000_000),
+): bigint {
+  return BigInt(deadlineMs) * 1_000_000n + BigInt(randomInt);
+}