@nadohq/mobile-client 0.29.0 → 0.31.0

package/src/signing/types.ts

@@ -1,10 +1,7 @@
 import { WalletClientWithAccount } from '@nadohq/shared';
 import { Hex } from 'viem';
 import { MobileSignedRequestParams } from '../types/clientTypes';
-import {
-  MobileNotificationPlatform,
-  MobileServerNotificationPreferences,
-} from '../types/serverModelTypes';
+import { MobileNotificationPlatform } from '../types/serverModelTypes';
 
 /**
  * Unsigned inner payloads that can be authenticated against the mobile service API.
@@ -16,8 +13,7 @@ import {
  * {@link canonicalizeMobileInner}, which is the source of truth. Keep the field order here in sync with it.
  */
 export type MobileSignedInner =
-  | { type: 'claim_username'; display_name: string }
-  | { type: 'update_username'; display_name: string }
+  | { type: 'set_username'; display_name: string }
   | { type: 'set_private_mode'; private_mode: boolean }
   | { type: 'self_identity' }
   | {
@@ -29,12 +25,6 @@ export type MobileSignedInner =
       locale: string | null;
       app_version: string | null;
     }
-  | { type: 'unregister_expo_token'; expo_token: string }
-  | {
-      type: 'update_preferences';
-      preferences: MobileServerNotificationPreferences;
-    }
-  | { type: 'notification_preferences' }
   | { type: 'registered_devices' };
 
 /**

package/src/types/MobileServerFailureError.ts

@@ -1,8 +1,6 @@
 import { BaseServerFailureError } from '@nadohq/shared';
-import {
-  MobileServerFailureResponse,
-  MobileServerRequestType,
-} from './serverBaseTypes';
+import { MobileServerFailureResponse } from './serverBaseTypes';
+import { MobileServerRequestType } from './serverRequestTypes';
 
 /**
  * Error thrown when the mobile service API returns a failure envelope, either as a non-2xx HTTP response

package/src/types/clientTypes.ts

@@ -1,39 +1,47 @@
 import { SignatureParams, Subaccount } from '@nadohq/shared';
 import { Hex } from 'viem';
 import {
+  MobileFeedMarginMode,
+  MobileFeedTradePosition,
   MobileNotificationCategory,
   MobileNotificationPlatform,
 } from './serverModelTypes';
 
 /**
- * A subaccount's claimed identity on the mobile service API.
+ * A subaccount's identity on the mobile service API. Every non-isolated subaccount has one implicitly, so
+ * both name fields are `null` until a username is claimed — render a local fallback label in that case and
+ * key lookups, links, and caches off `subaccount`.
  *
  * `username` and `displayName` are two representations of the same claimed name: `displayName` is what the
  * user entered (preserving casing, e.g. `Alice.One`), while `username` is the canonical, lowercased handle
- * derived from it (e.g. `alice.one`). `username` is the unique key used for profile lookups
- * ({@link MobilePublicProfile}); `displayName` is only for presentation.
+ * derived from it (e.g. `alice.one`), unique across identities.
  */
 export interface MobileIdentity {
   subaccount: Hex;
   /**
-   * Canonical, lowercased handle derived from {@link MobileIdentity.displayName}, unique per identity and
-   * used for profile lookups.
+   * Canonical, lowercased handle derived from {@link MobileIdentity.displayName}, unique across identities,
+   * or `null` if no username has been claimed.
    */
-  username: string;
+  username: string | null;
   /**
-   * User-facing name as claimed, preserving original casing. Validated against `MOBILE_DISPLAY_NAME_PATTERN`.
+   * User-facing name as claimed, preserving original casing, or `null` if no username has been claimed.
+   * Validated against `MOBILE_DISPLAY_NAME_PATTERN`.
    */
-  displayName: string;
+  displayName: string | null;
   privateMode: boolean;
 }
 
 /**
- * A subaccount's public profile, as returned by an unsigned profile lookup.
+ * A subaccount's public profile, as returned by an unsigned profile lookup. Private Mode hides the account's
+ * activity, not its profile, so `privateMode` is exposed here too.
  */
 export interface MobilePublicProfile {
   subaccount: Hex;
-  username: string;
-  displayName: string;
+  /** Canonical, lowercased handle, or `null` if no username has been claimed. */
+  username: string | null;
+  /** User-facing name as claimed, or `null` if no username has been claimed. */
+  displayName: string | null;
+  privateMode: boolean;
 }
 
 /**
@@ -44,6 +52,58 @@ export interface MobileUsernameAvailability {
   available: boolean;
 }
 
+/**
+ * Margin of a feed trade. Branch on `mode` — do not infer isolated state from leverage presence:
+ * `estimatedLeverage` (a rounded whole-number estimate, not exact submitted leverage) is `undefined` on
+ * `cross`, and also `undefined` inside `isolated` when no estimate is available.
+ */
+export interface MobileFeedMargin {
+  mode: MobileFeedMarginMode;
+  estimatedLeverage?: number;
+}
+
+/**
+ * A single feed trade: one row per order digest, enriched with the trader's current identity at read time
+ * (a rename can change an already-fetched trade on the next read). Amounts are display-oriented human-unit
+ * numbers — do not use them for accounting, order construction, or exact threshold decisions.
+ */
+export interface MobileFeedTrade {
+  /** Order digest this trade is keyed by; the stable id for reconciling live pagination. */
+  orderDigest: Hex;
+  subaccount: Hex;
+  /** `null` when the trader has not claimed a username; render a local fallback label from `subaccount`. */
+  username: string | null;
+  /** `null` when the trader has not claimed a username; render a local fallback label from `subaccount`. */
+  displayName: string | null;
+  /** Reserved for a future avatar source; `null` until one is implemented. */
+  avatarUrl: string | null;
+  productId: number;
+  /** Executed quantity in human units. */
+  quantity: number;
+  /** Trade notional in whole-dollar human units. */
+  notional: number;
+  /** Average execution price in human units. */
+  averagePrice: number;
+  margin: MobileFeedMargin;
+  /** Resulting position change. `position.direction` is NOT the execution buy/sell side. */
+  position: MobileFeedTradePosition;
+  /** Realized PnL of the trade in human units; can be negative. */
+  realizedPnl: number;
+  /** Fill time as a Unix timestamp (milliseconds). */
+  filledAt: number;
+}
+
+/**
+ * A page of feed trades. `nextCursor` is `null` when there was no additional candidate at query time.
+ * Pagination is live, not snapshot, so a later fill can move a trade between pages — deduplicate by
+ * {@link MobileFeedTrade.orderDigest} and treat the merged list as a short-lived view, not an authoritative
+ * cache (removals from Private Mode or blacklists are not signaled).
+ */
+export interface MobileFeedPage {
+  trades: MobileFeedTrade[];
+  nextCursor: string | null;
+}
+
 /**
  * Scope limiting a notification category preference. Scopes are part of the wire format but rejected by the
  * backend for the MVP — `scopes` must be empty.
@@ -98,6 +158,16 @@ export interface MobileRegisteredDevice {
 export interface MobileSignedRequestParams
   extends Subaccount, SignatureParams {}
 
+/**
+ * Common params for the unsigned notification requests, which name their target with an Expo push token
+ * instead of a subaccount and signature — the counterpart to {@link MobileSignedRequestParams}. The backend
+ * resolves the token's owning wallet and reads or mutates that wallet's state.
+ */
+export interface MobileWithExpoTokenParams {
+  /** Expo push token, e.g. `ExponentPushToken[...]`. */
+  expoToken: string;
+}
+
 /**
  * Params for {@link MobileClient.getUsernameAvailability}.
  */
@@ -108,26 +178,36 @@ export interface GetMobileUsernameAvailabilityParams {
 /**
  * Params for {@link MobileClient.getPublicProfile}.
  */
-export interface GetMobilePublicProfileParams {
-  username: string;
-}
+export type GetMobilePublicProfileParams = Subaccount;
 
 /**
- * Params for {@link MobileClient.getSelfIdentity}.
+ * Params for {@link MobileClient.getFeed}.
  */
-export type GetMobileSelfIdentityParams = MobileSignedRequestParams;
+export interface GetMobileFeedParams {
+  /**
+   * Minimum notional filter as a whole-dollar safe integer, at least `MOBILE_FEED_MIN_NOTIONAL_FLOOR`
+   * ($1,000). Omit for the unfiltered feed.
+   */
+  minimumNotional?: number;
+  /** Page size, 1–`MOBILE_FEED_MAX_PAGE_SIZE` (50); the backend defaults to 50 when omitted. */
+  limit?: number;
+  /**
+   * Opaque keyset cursor from a prior page's {@link MobileFeedPage.nextCursor}. Send it back unchanged with
+   * the exact same `minimumNotional` it was issued for.
+   */
+  cursor?: string;
+}
 
 /**
- * Params for {@link MobileClient.claimUsername}.
+ * Params for {@link MobileClient.getSelfIdentity}.
  */
-export interface MobileClaimUsernameParams extends MobileSignedRequestParams {
-  displayName: string;
-}
+export type GetMobileSelfIdentityParams = MobileSignedRequestParams;
 
 /**
- * Params for {@link MobileClient.updateUsername}.
+ * Params for {@link MobileClient.setUsername}.
  */
-export interface MobileUpdateUsernameParams extends MobileSignedRequestParams {
+export interface MobileSetUsernameParams extends MobileSignedRequestParams {
+  /** User-facing name to claim, preserving casing. Must match `MOBILE_DISPLAY_NAME_PATTERN`. */
   displayName: string;
 }
 
@@ -160,21 +240,19 @@ export interface MobileRegisterExpoTokenParams extends MobileSignedRequestParams
 /**
  * Params for {@link MobileClient.unregisterExpoToken}.
  */
-export interface MobileUnregisterExpoTokenParams extends MobileSignedRequestParams {
-  expoToken: string;
-}
+export type MobileUnregisterExpoTokenParams = MobileWithExpoTokenParams;
 
 /**
  * Params for {@link MobileClient.updateNotificationPreferences}.
  */
-export interface MobileUpdateNotificationPreferencesParams extends MobileSignedRequestParams {
+export interface MobileUpdateNotificationPreferencesParams extends MobileWithExpoTokenParams {
   preferences: MobileNotificationPreferences;
 }
 
 /**
  * Params for {@link MobileClient.getNotificationPreferences}.
  */
-export type GetMobileNotificationPreferencesParams = MobileSignedRequestParams;
+export type GetMobileNotificationPreferencesParams = MobileWithExpoTokenParams;
 
 /**
  * Params for {@link MobileClient.getRegisteredDevices}.

package/src/types/index.ts

@@ -5,3 +5,4 @@ export * from './serverBaseTypes';
 export * from './serverExecuteTypes';
 export * from './serverModelTypes';
 export * from './serverQueryTypes';
+export * from './serverRequestTypes';

package/src/types/mobileErrorCodes.ts

@@ -1,22 +1,25 @@
 import { NADO_ERROR_CODES } from '@nadohq/shared';
 
 /**
- * Numeric error codes returned by the mobile service API. Identity codes (61xx) and notification codes
- * (62xx) are mobile-specific; the remaining codes are shared cross-service codes from the backend's common
- * error enum, inlined via spread from {@link NADO_ERROR_CODES}.
+ * Numeric error codes returned by the mobile service API. Identity codes (61xx), notification codes (62xx),
+ * and feed codes (63xx) are mobile-specific; the remaining codes are shared cross-service codes from the
+ * backend's common error enum, inlined via spread from {@link NADO_ERROR_CODES}.
  */
 export const MOBILE_ERROR_CODES = {
   ...NADO_ERROR_CODES,
   INVALID_DISPLAY_NAME: 6100,
   USERNAME_UNAVAILABLE: 6101,
-  IDENTITY_ALREADY_CLAIMED: 6102,
-  IDENTITY_REQUIRED: 6103,
   INVALID_IDENTITY_TARGET: 6104,
+  /** Another identity write for the subaccount committed with a later nonce. Re-read before retrying. */
   STALE_IDENTITY_UPDATE: 6105,
   PROFILE_NOT_FOUND: 6106,
   INVALID_EXPO_TOKEN: 6200,
   INVALID_DEVICE_METADATA: 6201,
   INVALID_PREFERENCES: 6202,
+  /** Feed `minimumNotional` or `limit` is outside its allowed domain. Fix the request; do not retry unchanged. */
+  INVALID_FEED_FILTER: 6300,
+  /** Feed cursor is malformed or bound to a different filter. Discard it and restart from the first page. */
+  INVALID_FEED_CURSOR: 6301,
 } as const;
 
 /**

package/src/types/serverBaseTypes.ts

@@ -1,35 +1,14 @@
-/**
- * Params for each unsigned `public_query`, keyed by request `type`.
- */
-export interface MobileServerPublicQueryParamsByType {
-  username_availability: { display_name: string };
-  profile: { username: string };
-}
-
-/**
- * Discriminant `type` values for unsigned `public_query` requests.
- */
-export type MobileServerPublicQueryType =
-  keyof MobileServerPublicQueryParamsByType;
+import { MobileServerRequestType } from './serverRequestTypes';
 
 /**
- * Wire `request_type` the backend echoes on failure envelopes, prefixed by route (`public_query_*`,
- * `query_*`, `execute_*`, e.g. `execute_claim_username`). Public-query types are enumerated; signed
- * query/execute names are kept as a `${prefix}_${string}` template to avoid duplicating the signed-type
- * tags declared in `signing.ts`.
+ * Base success envelope shared by every mobile service API route: just the `status` discriminant. Query
+ * routes intersect this with their payload (see {@link MobileServerPublicQuerySuccessResponse}), inlining the
+ * payload fields alongside `status` rather than nesting them under a `data` key like the engine does; execute
+ * routes return it as-is because they carry no payload.
  */
-export type MobileServerRequestType =
-  | `public_query_${MobileServerPublicQueryType}`
-  | `query_${string}`
-  | `execute_${string}`;
-
-/**
- * Successful mobile service API envelope, discriminated on `status`. Payload fields are inlined alongside
- * `status` rather than nested under a `data` key, matching the mobile backend's wire format.
- */
-export type MobileServerSuccessResponse<TData extends object = object> = {
+export interface MobileServerSuccessResponse {
   status: 'success';
-} & TData;
+}
 
 /**
  * Failure envelope returned by any mobile service API route. A response missing this envelope shape

package/src/types/serverExecuteTypes.ts

@@ -2,6 +2,23 @@ import {
   MobileServerFailureResponse,
   MobileServerSuccessResponse,
 } from './serverBaseTypes';
+import {
+  MobileServerPublicExecuteRequestByType,
+  MobileServerPublicExecuteRequestType,
+} from './serverRequestTypes';
+
+/**
+ * Unsigned `public_execute` request body: a `type` discriminant flattened with its params, mirroring
+ * {@link MobileServerPublicQueryRequest}.
+ */
+export type MobileServerPublicExecuteRequest<
+  T extends MobileServerPublicExecuteRequestType =
+    MobileServerPublicExecuteRequestType,
+> = {
+  [K in MobileServerPublicExecuteRequestType]: {
+    type: K;
+  } & MobileServerPublicExecuteRequestByType[K];
+}[T];
 
 /**
  * Discriminated `execute` result union. Mobile execute routes return no payload beyond the success

package/src/types/serverModelTypes.ts

@@ -1,3 +1,4 @@
+import { BalanceSide } from '@nadohq/shared';
 import { Hex } from 'viem';
 
 /**
@@ -17,24 +18,119 @@ export type MobileNotificationCategory =
   | 'announcement';
 
 /**
- * Server-side public profile shape (snake_case).
+ * Server-side public profile shape (snake_case). Name fields are `null` until the subaccount claims a
+ * username.
  */
 export interface MobileServerProfile {
   subaccount: Hex;
-  username: string;
-  display_name: string;
+  username: string | null;
+  display_name: string | null;
+  private_mode: boolean;
 }
 
 /**
- * Server-side identity shape (snake_case) returned by the signed `self_identity` query.
+ * Server-side identity shape (snake_case) returned by the signed `self_identity` query. Name fields are
+ * `null` until the subaccount claims a username.
  */
 export interface MobileServerIdentity {
   subaccount: Hex;
-  username: string;
-  display_name: string;
+  username: string | null;
+  display_name: string | null;
   private_mode: boolean;
 }
 
+/**
+ * Direction of the position a feed trade resulted in — for `closed`, the direction that was closed. This is
+ * NOT the execution buy/sell side, which the feed does not expose. Aliases {@link BalanceSide} so the feed's
+ * direction values stay in lockstep with the rest of the SDK.
+ */
+export type MobileFeedTradePositionDirection = BalanceSide;
+
+/**
+ * Every {@link MobileFeedTradePositionDirection} the feed can report, for callers that need the values at
+ * runtime (validation, filters, UI enumeration).
+ */
+export const MOBILE_FEED_TRADE_POSITION_DIRECTIONS = [
+  'long',
+  'short',
+] as const satisfies readonly MobileFeedTradePositionDirection[];
+
+/**
+ * Every {@link MobileFeedTradePositionEffect} the feed can report, for callers that need the values at
+ * runtime (validation, filters, UI enumeration).
+ */
+export const MOBILE_FEED_TRADE_POSITION_EFFECTS = [
+  'opened',
+  'increased',
+  'reduced',
+  'closed',
+  'flipped',
+] as const;
+
+/**
+ * How a feed trade changed the trader's position in the product.
+ */
+export type MobileFeedTradePositionEffect =
+  (typeof MOBILE_FEED_TRADE_POSITION_EFFECTS)[number];
+
+/**
+ * Position change of a feed trade. Both keys are single words, so the wire and client shapes are identical
+ * and this type is shared by {@link MobileServerFeedTrade} and the client-side `MobileFeedTrade`.
+ */
+export interface MobileFeedTradePosition {
+  direction: MobileFeedTradePositionDirection;
+  effect: MobileFeedTradePositionEffect;
+}
+
+/**
+ * Every {@link MobileFeedMarginMode} the feed can report, for callers that need the values at runtime
+ * (validation, filters, UI enumeration).
+ */
+export const MOBILE_FEED_MARGIN_MODES = ['cross', 'isolated'] as const;
+
+/**
+ * Margin mode a feed trade was executed under. Shared by the wire and client margin shapes.
+ */
+export type MobileFeedMarginMode = (typeof MOBILE_FEED_MARGIN_MODES)[number];
+
+/**
+ * Server-side margin of a feed trade. Branch on `mode` — do not infer isolated state from leverage presence:
+ * `estimated_leverage` (a rounded whole-number estimate, not exact submitted leverage) is omitted on `cross`,
+ * and also omitted inside `isolated` when no estimate is available.
+ */
+export interface MobileServerFeedMargin {
+  mode: MobileFeedMarginMode;
+  estimated_leverage?: number;
+}
+
+/**
+ * Server-side feed trade shape (snake_case): one row per order digest, enriched at read time with the
+ * trader's current identity. Amounts are display-oriented human-unit JSON numbers — do not use them for
+ * accounting, order construction, or exact threshold decisions.
+ */
+export interface MobileServerFeedTrade {
+  /** Order digest this row is keyed by; the stable id clients use to reconcile live pagination. */
+  order_digest: Hex;
+  subaccount: Hex;
+  username: string | null;
+  display_name: string | null;
+  /** Reserved for a future avatar source; `null` until one is implemented. */
+  avatar_url: string | null;
+  product_id: number;
+  /** Executed quantity in human units. */
+  quantity: number;
+  /** Trade notional in whole-dollar human units. */
+  notional: number;
+  /** Average execution price in human units. */
+  average_price: number;
+  margin: MobileServerFeedMargin;
+  position: MobileFeedTradePosition;
+  /** Realized PnL of the trade in human units; can be negative. */
+  realized_pnl: number;
+  /** Fill time as JavaScript-safe integer Unix milliseconds. */
+  filled_at_ms: number;
+}
+
 /**
  * Server-side scope limiting a notification category preference. Scopes are rejected by the backend for the
  * MVP (`scopes` must be empty) but are part of the wire format.
@@ -53,8 +149,8 @@ export interface MobileServerNotificationCategoryPreference {
 }
 
 /**
- * Server-side notification preferences shape (snake_case), used in both the `update_preferences` execute and
- * the `notification_preferences` query response.
+ * Server-side notification preferences shape (snake_case), used in both the `update_preferences` public
+ * execute and the `notification_preferences` public query response.
  */
 export interface MobileServerNotificationPreferences {
   /** Only `1` is accepted by the backend for the MVP. */

package/src/types/serverQueryTypes.ts

@@ -1,74 +1,119 @@
+import { MobileServerSuccessResponse } from './serverBaseTypes';
 import {
-  MobileServerPublicQueryParamsByType,
-  MobileServerPublicQueryType,
-  MobileServerSuccessResponse,
-} from './serverBaseTypes';
-import {
+  MobileServerFeedTrade,
   MobileServerIdentity,
   MobileServerNotificationPreferences,
   MobileServerProfile,
   MobileServerRegisteredDevice,
 } from './serverModelTypes';
+import {
+  MobileServerPublicQueryRequestByType,
+  MobileServerPublicQueryRequestType,
+  MobileServerSignedQueryRequestType,
+} from './serverRequestTypes';
 
 /**
  * Unsigned `public_query` request body: a `type` discriminant flattened with its params.
  */
 export type MobileServerPublicQueryRequest<
-  T extends MobileServerPublicQueryType = MobileServerPublicQueryType,
+  T extends MobileServerPublicQueryRequestType =
+    MobileServerPublicQueryRequestType,
 > = {
-  [K in MobileServerPublicQueryType]: {
+  [K in MobileServerPublicQueryRequestType]: {
     type: K;
-  } & MobileServerPublicQueryParamsByType[K];
+  } & MobileServerPublicQueryRequestByType[K];
 }[T];
 
 /**
- * Request body for the `username_availability` public query.
+ * Payload of the `username_availability` public query success response.
  */
-export type MobileServerUsernameAvailabilityRequest =
-  MobileServerPublicQueryRequest<'username_availability'>;
+export interface MobileServerUsernameAvailabilityResponse {
+  username: string;
+  available: boolean;
+}
 
 /**
- * Request body for the `profile` public query.
+ * Payload of the `profile` public query success response.
  */
-export type MobileServerProfileRequest =
-  MobileServerPublicQueryRequest<'profile'>;
+export interface MobileServerProfileResponse {
+  profile: MobileServerProfile;
+}
 
 /**
- * Successful response for the `username_availability` public query.
+ * Payload of the `feed` public query success response.
  */
-export type MobileServerUsernameAvailabilityResponse =
-  MobileServerSuccessResponse<{
-    username: string;
-    available: boolean;
-  }>;
+export interface MobileServerFeedResponse {
+  trades: MobileServerFeedTrade[];
+  /**
+   * `null` when there was no additional candidate at query time; a page may contain fewer than `limit` trades
+   * (or none) with a non-null cursor because invalid enrichment rows are omitted and pagination is live
+   * rather than snapshot.
+   */
+  next_cursor: string | null;
+}
 
 /**
- * Successful response for the `profile` public query.
+ * Payload of the signed `self_identity` query success response. Every non-isolated subaccount has an implicit
+ * identity, so the backend returns one for any valid sender, with `null` name fields when no username has
+ * been claimed; `identity` stays nullable to match the backend's `Option`.
  */
-export type MobileServerProfileResponse = MobileServerSuccessResponse<{
-  profile: MobileServerProfile;
-}>;
+export interface MobileServerSelfIdentityResponse {
+  identity: MobileServerIdentity | null;
+}
 
 /**
- * Successful response for the signed `self_identity` query. A `null` identity means the subaccount has not
- * claimed a username yet — this is normal data, not an error.
+ * Payload of the `notification_preferences` public query success response.
  */
-export type MobileServerSelfIdentityResponse = MobileServerSuccessResponse<{
-  identity: MobileServerIdentity | null;
-}>;
+export interface MobileServerNotificationPreferencesResponse {
+  preferences: MobileServerNotificationPreferences;
+}
+
+/**
+ * Payload of the signed `registered_devices` query success response.
+ */
+export interface MobileServerRegisteredDevicesResponse {
+  devices: MobileServerRegisteredDevice[];
+}
+
+/**
+ * Success payloads for each unsigned `public_query`, keyed by request `type`. Counterpart to
+ * {@link MobileServerPublicQueryRequestByType} so a query's request params and response share one lookup,
+ * matching engine's `EngineServerQueryResponseByType`. Holds the unwrapped payload; the envelope is applied
+ * by {@link MobileServerPublicQuerySuccessResponse}.
+ */
+export interface MobileServerPublicQueryResponseByType {
+  username_availability: MobileServerUsernameAvailabilityResponse;
+  profile: MobileServerProfileResponse;
+  feed: MobileServerFeedResponse;
+  notification_preferences: MobileServerNotificationPreferencesResponse;
+}
+
+/**
+ * Success payloads for each signed `query`, keyed by request `type`. Counterpart to
+ * {@link MobileServerSignedQueryRequestByType} so a signed query's request params and response share one
+ * lookup, matching the public route. Holds the unwrapped payload; the envelope is applied by
+ * {@link MobileServerSignedQuerySuccessResponse}.
+ */
+export interface MobileServerSignedQueryResponseByType {
+  self_identity: MobileServerSelfIdentityResponse;
+  registered_devices: MobileServerRegisteredDevicesResponse;
+}
 
 /**
- * Successful response for the signed `notification_preferences` query.
+ * Full success response for an unsigned `public_query`: the {@link MobileServerSuccessResponse} envelope with
+ * the query's payload inlined alongside `status`. Derived from {@link MobileServerPublicQueryResponseByType},
+ * mirroring engine's `EngineServerQuerySuccessResponse` (inlined here instead of nested under `data`).
  */
-export type MobileServerNotificationPreferencesResponse =
-  MobileServerSuccessResponse<{
-    preferences: MobileServerNotificationPreferences;
-  }>;
+export type MobileServerPublicQuerySuccessResponse<
+  T extends MobileServerPublicQueryRequestType =
+    MobileServerPublicQueryRequestType,
+> = MobileServerSuccessResponse & MobileServerPublicQueryResponseByType[T];
 
 /**
- * Successful response for the signed `registered_devices` query.
+ * Full success response for a signed `query`: the {@link MobileServerSuccessResponse} envelope with the
+ * query's payload inlined alongside `status`. Derived from {@link MobileServerSignedQueryResponseByType}.
  */
-export type MobileServerRegisteredDevicesResponse =
-  MobileServerSuccessResponse<{
-    devices: MobileServerRegisteredDevice[];
-  }>;
+export type MobileServerSignedQuerySuccessResponse<
+  T extends MobileServerSignedQueryRequestType =
+    MobileServerSignedQueryRequestType,
+> = MobileServerSuccessResponse & MobileServerSignedQueryResponseByType[T];