@nadohq/mobile-client 0.27.0

package/src/signing/payloadHash.ts

@@ -0,0 +1,12 @@
+import { encode } from '@msgpack/msgpack';
+import { Hex, keccak256 } from 'viem';
+import { MobileSignedInner } from './types';
+
+/**
+ * Computes the EIP-712 `payloadHash` for a canonicalized inner payload: `keccak256(msgpack(inner))`.
+ *
+ * @param inner - A canonicalized inner payload; callers must run {@link canonicalizeMobileInner} first.
+ */
+export function getMobilePayloadHash(inner: MobileSignedInner): Hex {
+  return keccak256(encode(inner));
+}

package/src/signing/signing.test.ts

@@ -0,0 +1,224 @@
+import { describe, expect, it } from '@jest/globals';
+import {
+  getNadoEIP712Domain,
+  getNadoEIP712PrimaryType,
+  getNadoEIP712Types,
+  subaccountToHex,
+} from '@nadohq/shared';
+import { createWalletClient, http, recoverTypedDataAddress } from 'viem';
+import { privateKeyToAccount } from 'viem/accounts';
+import { ink } from 'viem/chains';
+import { buildSignedMobileRequest } from './buildSignedMobileRequest';
+import { canonicalizeMobileInner } from './canonicalize';
+import { getMobileNonce } from './nonce';
+import { getMobilePayloadHash } from './payloadHash';
+import { MobileSignedInner } from './types';
+
+// Fixed test key — these tests are offline (no network I/O) and only exercise local signing/hashing logic.
+const FIXED_PRIVATE_KEY =
+  '0x59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b786907' as const;
+const FIXED_VERIFYING_ADDR = '0x0000000000000000000000000000000000000001';
+
+const PINNED_HASHES = {
+  claim_username:
+    '0xcfbe9e0a546f43f6d68f86b38cf260ffe079af1915800c0e6df8724ddb6f2dff',
+  update_username:
+    '0x92c3831d30de8206f9ee9d4cf29ed2a2fb1612a3b818e2e46121fc1d5eb4edb6',
+  set_private_mode:
+    '0x4d12a06234d751e6ddcc01d8f70836bb5b7e207e573641d1efb5aaf2b0f30d10',
+  self_identity:
+    '0x10e94c4502cade0a0b4d7469717bcc1d266fc6a3b7635236fa1d3600b58c9954',
+  // The three execute hashes below mirror the backend's pinned fixtures in mobile/src/api/types.rs.
+  register_expo_token:
+    '0x1b9471afc9bde66f9bffd576d3326420e1bade4e16afa3a73ddc65f27155611c',
+  unregister_expo_token:
+    '0xd131071d0898c97496f3d41dfc05f30a5f82c95e550944c4fba47419ddd0ebf3',
+  update_preferences:
+    '0x071b8ac6f3d2518267dd238c8c96e15e07e0552aede3ba32383706bb05726f83',
+  notification_preferences:
+    '0x3694dda0e5732b36eb3b60da6b147ec4e35520fc54529610c69d19d722d4fe97',
+  registered_devices:
+    '0xe77b42e32d27f054f86d5ed52c9aac7b3eed857eb6209ee883c92f01b84d3334',
+} as const;
+
+describe('[mobile-client]: signing (offline)', () => {
+  describe('pinned payload hashes', () => {
+    it('claim_username', () => {
+      const inner: MobileSignedInner = {
+        type: 'claim_username',
+        display_name: 'Alice.One',
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.claim_username);
+    });
+
+    it('update_username', () => {
+      const inner: MobileSignedInner = {
+        type: 'update_username',
+        display_name: 'Alice.Two',
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.update_username);
+    });
+
+    it('set_private_mode', () => {
+      const inner: MobileSignedInner = {
+        type: 'set_private_mode',
+        private_mode: true,
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.set_private_mode);
+    });
+
+    it('self_identity', () => {
+      const inner: MobileSignedInner = { type: 'self_identity' };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.self_identity);
+    });
+
+    it('register_expo_token', () => {
+      const inner: MobileSignedInner = {
+        type: 'register_expo_token',
+        expo_token: 'ExponentPushToken[abcdef1234567890abcdef]',
+        platform: 'ios',
+        locale: 'en-GB',
+        app_version: '1.2.3',
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.register_expo_token);
+    });
+
+    it('unregister_expo_token', () => {
+      const inner: MobileSignedInner = {
+        type: 'unregister_expo_token',
+        expo_token: 'ExponentPushToken[abcdef1234567890abcdef]',
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.unregister_expo_token);
+    });
+
+    it('update_preferences', () => {
+      const inner: MobileSignedInner = {
+        type: 'update_preferences',
+        preferences: {
+          schema_version: 1,
+          categories: [{ category: 'order_fill', enabled: true, scopes: [] }],
+        },
+      };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.update_preferences);
+    });
+
+    it('notification_preferences', () => {
+      const inner: MobileSignedInner = { type: 'notification_preferences' };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.notification_preferences);
+    });
+
+    it('registered_devices', () => {
+      const inner: MobileSignedInner = { type: 'registered_devices' };
+      const hash = getMobilePayloadHash(canonicalizeMobileInner(inner));
+      expect(hash).toBe(PINNED_HASHES.registered_devices);
+    });
+  });
+
+  it('canonicalizes msgpack key order regardless of input key order', () => {
+    // Deliberately construct the inner payload with `type` last — canonicalizeMobileInner must rebuild it
+    // with `type` first so the msgpack encoding (and therefore the payload hash) is deterministic.
+    const outOfOrderInner = {
+      private_mode: true,
+      type: 'set_private_mode',
+    } as MobileSignedInner;
+
+    const hash = getMobilePayloadHash(canonicalizeMobileInner(outOfOrderInner));
+    expect(hash).toBe(PINNED_HASHES.set_private_mode);
+  });
+
+  it('canonicalizes nested preference key order regardless of input key order', () => {
+    // Nested preference objects must also be rebuilt in the backend's struct declaration order
+    // (schema_version, categories; category, enabled, scopes) for the msgpack hash to be deterministic.
+    const outOfOrderInner = {
+      preferences: {
+        categories: [{ scopes: [], enabled: true, category: 'order_fill' }],
+        schema_version: 1,
+      },
+      type: 'update_preferences',
+    } as unknown as MobileSignedInner;
+
+    const hash = getMobilePayloadHash(canonicalizeMobileInner(outOfOrderInner));
+    expect(hash).toBe(PINNED_HASHES.update_preferences);
+  });
+
+  describe('nonce generation', () => {
+    it('encodes a ~30s-ahead receive deadline as a bigint', () => {
+      const before = Date.now();
+      const nonce = getMobileNonce();
+      const after = Date.now();
+
+      expect(typeof nonce).toBe('bigint');
+
+      const deadlineMs = nonce / 1_000_000n;
+      expect(deadlineMs >= BigInt(before + 29_000)).toBe(true);
+      expect(deadlineMs <= BigInt(after + 30_000)).toBe(true);
+    });
+
+    it('produces distinct nonces on successive calls', () => {
+      const a = getMobileNonce();
+      const b = getMobileNonce();
+      expect(a).not.toBe(b);
+    });
+  });
+
+  it('signs a request that recovers to the expected signer with a correctly flattened body', async () => {
+    const account = privateKeyToAccount(FIXED_PRIVATE_KEY);
+    const walletClient = createWalletClient({
+      account,
+      chain: ink,
+      transport: http(),
+    });
+
+    const subaccountOwner = account.address;
+    const subaccountName = 'default';
+    const chainId = ink.id;
+    const verifyingAddr = FIXED_VERIFYING_ADDR;
+    const nonce = 30_000_000_000_000n;
+
+    const signedRequest = await buildSignedMobileRequest({
+      walletClient,
+      subaccountOwner,
+      subaccountName,
+      chainId,
+      verifyingAddr,
+      inner: { type: 'set_private_mode', private_mode: true },
+      nonce,
+    });
+
+    expect(signedRequest.type).toBe('set_private_mode');
+    expect(signedRequest.private_mode).toBe(true);
+    expect(signedRequest.nonce).toBe(nonce.toString());
+
+    const expectedSender = subaccountToHex({
+      subaccountOwner,
+      subaccountName,
+    }).toLowerCase();
+    expect(signedRequest.sender).toBe(expectedSender);
+
+    const payloadHash = getMobilePayloadHash(
+      canonicalizeMobileInner({ type: 'set_private_mode', private_mode: true }),
+    );
+    const recoveredAddress = await recoverTypedDataAddress({
+      domain: getNadoEIP712Domain(verifyingAddr, chainId),
+      types: getNadoEIP712Types('nado_authentication'),
+      primaryType: getNadoEIP712PrimaryType('nado_authentication'),
+      message: {
+        method: 'mobile:execute_set_private_mode',
+        sender: signedRequest.sender,
+        payloadHash,
+        nonce,
+      },
+      signature: signedRequest.signature,
+    });
+
+    expect(recoveredAddress.toLowerCase()).toBe(account.address.toLowerCase());
+  });
+});

package/src/signing/types.ts

@@ -0,0 +1,71 @@
+import { WalletClientWithAccount } from '@nadohq/shared';
+import { Hex } from 'viem';
+import { MobileSignedRequestParams } from '../types/clientTypes';
+import {
+  MobileNotificationPlatform,
+  MobileServerNotificationPreferences,
+} from '../types/serverModelTypes';
+
+/**
+ * Unsigned inner payloads that can be authenticated against the mobile service API.
+ *
+ * Key order is significant: the payload hash is `keccak256(msgpack(inner))`, and msgpack encodes object keys
+ * in insertion order, so every field of every sub-type must be serialized in the exact order the backend
+ * 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.
+ */
+export type MobileSignedInner =
+  | { type: 'claim_username'; display_name: string }
+  | { type: 'update_username'; display_name: string }
+  | { type: 'set_private_mode'; private_mode: boolean }
+  | { type: 'self_identity' }
+  | {
+      type: 'register_expo_token';
+      expo_token: string;
+      platform: MobileNotificationPlatform;
+      // Optional on the wire, but always present (null when unset) so the msgpack payload hash matches the
+      // backend, which serializes `Option::None` as nil under the same key.
+      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' };
+
+/**
+ * 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 }>,
+  'type'
+>;
+
+/**
+ * A signed mobile service API request body: the inner payload flattened with its signature, sender, and
+ * nonce (unlike the engine client, which wraps params under a `{ [type]: params }` key).
+ */
+export type MobileSignedRequest<
+  T extends MobileSignedInner = MobileSignedInner,
+> = T & {
+  signature: Hex;
+  sender: Hex;
+  nonce: string;
+};
+
+/**
+ * Params for {@link buildSignedMobileRequest}.
+ */
+export interface BuildSignedMobileRequestParams extends MobileSignedRequestParams {
+  walletClient: WalletClientWithAccount;
+  inner: MobileSignedInner;
+  /**
+   * Overrides the generated nonce; mainly useful for tests that pin the signed payload.
+   */
+  nonce?: bigint;
+}

package/src/types/MobileServerFailureError.ts

@@ -0,0 +1,18 @@
+import { MobileServerFailureResponse } from './serverBaseTypes';
+
+/**
+ * Error thrown when the mobile service API returns a failure envelope, either as a non-2xx HTTP response
+ * or a 2xx response with `status: 'failure'`.
+ */
+export class MobileServerFailureError extends Error {
+  constructor(
+    readonly responseData: MobileServerFailureResponse,
+    /**
+     * HTTP status code of the response, e.g. `404` for `PROFILE_NOT_FOUND`. Unlike the engine, the mobile
+     * backend maps domain failures onto HTTP statuses.
+     */
+    readonly httpStatus: number,
+  ) {
+    super(`${responseData.error_code}: ${responseData.error}`);
+  }
+}

package/src/types/clientTypes.ts

@@ -0,0 +1,182 @@
+import { SignatureParams, Subaccount } from '@nadohq/shared';
+import { Hex } from 'viem';
+import {
+  MobileNotificationCategory,
+  MobileNotificationPlatform,
+} from './serverModelTypes';
+
+/**
+ * A subaccount's claimed identity on the mobile service API.
+ *
+ * `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.
+ */
+export interface MobileIdentity {
+  subaccount: Hex;
+  /**
+   * Canonical, lowercased handle derived from {@link MobileIdentity.displayName}, unique per identity and
+   * used for profile lookups.
+   */
+  username: string;
+  /**
+   * User-facing name as claimed, preserving original casing. Validated against `MOBILE_DISPLAY_NAME_PATTERN`.
+   */
+  displayName: string;
+  privateMode: boolean;
+}
+
+/**
+ * A subaccount's public profile, as returned by an unsigned profile lookup.
+ */
+export interface MobilePublicProfile {
+  subaccount: Hex;
+  username: string;
+  displayName: string;
+}
+
+/**
+ * Result of a username availability check.
+ */
+export interface MobileUsernameAvailability {
+  username: string;
+  available: boolean;
+}
+
+/**
+ * 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.
+ */
+export type MobileNotificationPreferenceScope =
+  | { type: 'subaccount'; subaccount: Hex }
+  | { type: 'product'; productId: number };
+
+/**
+ * A per-category push notification preference.
+ */
+export interface MobileNotificationCategoryPreference {
+  category: MobileNotificationCategory;
+  enabled: boolean;
+  scopes: MobileNotificationPreferenceScope[];
+}
+
+/**
+ * A wallet's push notification preferences. The backend requires exactly one entry per known category and
+ * `schemaVersion` of 1.
+ */
+export interface MobileNotificationPreferences {
+  /** Only `1` is accepted by the backend for the MVP. */
+  schemaVersion: 1;
+  categories: MobileNotificationCategoryPreference[];
+}
+
+/**
+ * A device registered for push notifications.
+ */
+export interface MobileRegisteredDevice {
+  /** Push platform the device registered under. */
+  platform: MobileNotificationPlatform;
+  /** BCP-47 locale tag reported at registration, or `null` if none was provided. */
+  locale: string | null;
+  /** App version string reported at registration, or `null` if none was provided. */
+  appVersion: string | null;
+  /**
+   * First 8 hex chars of `keccak256` over the bracket-stripped Expo token — a stable, non-reversible
+   * identifier for the device's push token. The raw token is never returned by the backend.
+   */
+  tokenFingerprintPrefix: string;
+  /**
+   * Unix timestamp (milliseconds) of the device's last registration refresh.
+   */
+  lastSeenAt: number;
+}
+
+/**
+ * Common params for signed requests that authenticate as a given subaccount.
+ */
+export interface MobileSignedRequestParams
+  extends Subaccount, SignatureParams {}
+
+/**
+ * Params for {@link MobileClient.getUsernameAvailability}.
+ */
+export interface GetMobileUsernameAvailabilityParams {
+  displayName: string;
+}
+
+/**
+ * Params for {@link MobileClient.getPublicProfile}.
+ */
+export interface GetMobilePublicProfileParams {
+  username: string;
+}
+
+/**
+ * Params for {@link MobileClient.getSelfIdentity}.
+ */
+export type GetMobileSelfIdentityParams = MobileSignedRequestParams;
+
+/**
+ * Params for {@link MobileClient.claimUsername}.
+ */
+export interface MobileClaimUsernameParams extends MobileSignedRequestParams {
+  displayName: string;
+}
+
+/**
+ * Params for {@link MobileClient.updateUsername}.
+ */
+export interface MobileUpdateUsernameParams extends MobileSignedRequestParams {
+  displayName: string;
+}
+
+/**
+ * Params for {@link MobileClient.setPrivateMode}.
+ */
+export interface MobileSetPrivateModeParams extends MobileSignedRequestParams {
+  privateMode: boolean;
+}
+
+/**
+ * Params for {@link MobileClient.registerExpoToken}.
+ */
+export interface MobileRegisterExpoTokenParams extends MobileSignedRequestParams {
+  /**
+   * Expo push token, e.g. `ExponentPushToken[...]`.
+   */
+  expoToken: string;
+  platform: MobileNotificationPlatform;
+  /**
+   * BCP-47 locale tag, max 35 chars.
+   */
+  locale?: string;
+  /**
+   * App version string, max 64 chars.
+   */
+  appVersion?: string;
+}
+
+/**
+ * Params for {@link MobileClient.unregisterExpoToken}.
+ */
+export interface MobileUnregisterExpoTokenParams extends MobileSignedRequestParams {
+  expoToken: string;
+}
+
+/**
+ * Params for {@link MobileClient.updateNotificationPreferences}.
+ */
+export interface MobileUpdateNotificationPreferencesParams extends MobileSignedRequestParams {
+  preferences: MobileNotificationPreferences;
+}
+
+/**
+ * Params for {@link MobileClient.getNotificationPreferences}.
+ */
+export type GetMobileNotificationPreferencesParams = MobileSignedRequestParams;
+
+/**
+ * Params for {@link MobileClient.getRegisteredDevices}.
+ */
+export type GetMobileRegisteredDevicesParams = MobileSignedRequestParams;

package/src/types/index.ts

@@ -0,0 +1,7 @@
+export * from './clientTypes';
+export * from './mobileErrorCodes';
+export * from './MobileServerFailureError';
+export * from './serverBaseTypes';
+export * from './serverExecuteTypes';
+export * from './serverModelTypes';
+export * from './serverQueryTypes';

package/src/types/mobileErrorCodes.ts

@@ -0,0 +1,27 @@
+/**
+ * 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.
+ */
+export const MOBILE_ERROR_CODES = {
+  NOT_IMPLEMENTED: 4001,
+  INVALID_SIGNER: 2028,
+  SERVICE_UNAVAILABLE: 1006,
+  INVALID_DISPLAY_NAME: 6100,
+  USERNAME_UNAVAILABLE: 6101,
+  IDENTITY_ALREADY_CLAIMED: 6102,
+  IDENTITY_REQUIRED: 6103,
+  INVALID_IDENTITY_TARGET: 6104,
+  STALE_IDENTITY_UPDATE: 6105,
+  PROFILE_NOT_FOUND: 6106,
+  INVALID_EXPO_TOKEN: 6200,
+  INVALID_DEVICE_METADATA: 6201,
+  INVALID_PREFERENCES: 6202,
+  INTERNAL_ERROR: 5000,
+} as const;
+
+/**
+ * Union of all known mobile service API error codes.
+ */
+export type MobileErrorCode =
+  (typeof MOBILE_ERROR_CODES)[keyof typeof MOBILE_ERROR_CODES];

package/src/types/serverBaseTypes.ts

@@ -0,0 +1,43 @@
+/**
+ * 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;
+
+/**
+ * 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`.
+ */
+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> = {
+  status: 'success';
+} & TData;
+
+/**
+ * Failure envelope returned by any mobile service API route. A response missing this envelope shape
+ * (e.g. a malformed body, or a non-JSON response) is a transport-level error, not a domain error.
+ */
+export interface MobileServerFailureResponse {
+  status: 'failure';
+  error: string;
+  error_code: number;
+  request_type: MobileServerRequestType;
+}

package/src/types/serverExecuteTypes.ts

@@ -0,0 +1,12 @@
+import {
+  MobileServerFailureResponse,
+  MobileServerSuccessResponse,
+} from './serverBaseTypes';
+
+/**
+ * Discriminated `execute` result union. Mobile execute routes return no payload beyond the success
+ * discriminant, so the success arm is the base success envelope; failures use the uniform failure envelope.
+ */
+export type MobileServerExecuteResult =
+  | MobileServerSuccessResponse
+  | MobileServerFailureResponse;

package/src/types/serverModelTypes.ts

@@ -0,0 +1,74 @@
+import { Hex } from 'viem';
+
+/**
+ * Platform of a device registered for push notifications.
+ */
+export type MobileNotificationPlatform = 'ios' | 'android';
+
+/**
+ * Category of push notification.
+ */
+export type MobileNotificationCategory =
+  | 'order_fill'
+  | 'order_update'
+  | 'liquidation'
+  | 'funding'
+  | 'product_listing'
+  | 'announcement';
+
+/**
+ * Server-side public profile shape (snake_case).
+ */
+export interface MobileServerProfile {
+  subaccount: Hex;
+  username: string;
+  display_name: string;
+}
+
+/**
+ * Server-side identity shape (snake_case) returned by the signed `self_identity` query.
+ */
+export interface MobileServerIdentity {
+  subaccount: Hex;
+  username: string;
+  display_name: string;
+  private_mode: boolean;
+}
+
+/**
+ * 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.
+ */
+export type MobileServerNotificationPreferenceScope =
+  | { type: 'subaccount'; subaccount: Hex }
+  | { type: 'product'; product_id: number };
+
+/**
+ * Server-side per-category notification preference (snake_case).
+ */
+export interface MobileServerNotificationCategoryPreference {
+  category: MobileNotificationCategory;
+  enabled: boolean;
+  scopes: MobileServerNotificationPreferenceScope[];
+}
+
+/**
+ * Server-side notification preferences shape (snake_case), used in both the `update_preferences` execute and
+ * the `notification_preferences` query response.
+ */
+export interface MobileServerNotificationPreferences {
+  /** Only `1` is accepted by the backend for the MVP. */
+  schema_version: 1;
+  categories: MobileServerNotificationCategoryPreference[];
+}
+
+/**
+ * Server-side registered push device shape (snake_case).
+ */
+export interface MobileServerRegisteredDevice {
+  platform: MobileNotificationPlatform;
+  locale: string | null;
+  app_version: string | null;
+  token_fingerprint_prefix: string;
+  last_seen_at: number;
+}