@nadohq/mobile-client 0.65.0 → 0.66.0

package/src/types/clientTypes.ts

@@ -6,7 +6,11 @@ import {
   MobileFeedTradePosition,
   MobileFeedTradePositionDirection,
   MobileNotificationCategory,
+  MobileNotificationMinTradeSizeUsd,
   MobileNotificationPlatform,
+  MobileNotificationPositionThreshold,
+  MobileNotificationRouteName,
+  MobileNotificationTypeId,
   MobileSocialFeedAction,
   MobileSocialFeedActionPriceBasis,
   MobileSocialFeedActionResolution,
@@ -300,6 +304,212 @@ export interface MobileRegisteredWallet {
   lastSeenAt: number;
 }
 
+/** Device capabilities declared when registering a v2 device. */
+export interface MobileNotificationCapabilities {
+  /** Registration accepts only the v2 protocol. */
+  payloadVersions: [2];
+  /** Notification types the device can handle. */
+  typeIds: MobileNotificationTypeId[];
+  /** Supported named navigation destinations. */
+  routes: MobileNotificationRouteName[];
+}
+
+/** Latest device generation and saved capabilities, including legacy registrations. */
+export interface MobileNotificationRegistrationV2 {
+  /** Opaque generation string; do not convert to a JavaScript number. */
+  registrationGeneration: string;
+  /** Legacy registrations have empty type and route lists. */
+  capabilities: {
+    /** The single saved protocol version. */
+    payloadVersions: [1] | [2];
+    /** Supported notification types. */
+    typeIds: MobileNotificationTypeId[];
+    /** Supported navigation destinations. */
+    routes: MobileNotificationRouteName[];
+  };
+}
+
+/** Complete wallet-level notification settings; every field is required on replacement. */
+export interface MobileNotificationSettings {
+  /** Own position milestones and the initial weekly digest. */
+  myPositions: boolean;
+  /** Unique milestone thresholds; the minimum selects the starting tier. */
+  positionThresholds: MobileNotificationPositionThreshold[];
+  /** Combined order fill/update switch; does not control liquidation notifications. */
+  myOrders: boolean;
+  /** Ordinary followed-trader notifications; enabled bells override this switch. */
+  followingTrades: boolean;
+  /** Notifications about posts by followed traders. */
+  followingPosts: boolean;
+  /** Minimum trade size for trade notifications, in whole USD. */
+  minTradeSizeUsd: MobileNotificationMinTradeSizeUsd;
+  /** New followers and follow-backs. */
+  newFollowers: boolean;
+  /** Maps to the legacy announcement preference. */
+  announcements: boolean;
+  /** Opt-in trader streak and account drama discovery notifications. */
+  discovery: boolean;
+}
+
+/** Versioned settings document returned by v2 reads and writes. */
+export interface MobileNotificationSettingsV2 {
+  /** Settings schema version. */
+  schemaVersion: 2;
+  /** Settings revision, independent of subscription revisions. */
+  revision: number;
+  /** Full saved settings. */
+  settings: MobileNotificationSettings;
+}
+
+/** Wallet market subscriptions and the signing Identity's enabled trader bells. */
+export interface MobileNotificationSubscriptions {
+  /** Wallet-level subscription revision; refresh after every mutation. */
+  revision: number;
+  /** Whether the one-time local favorites import has completed. */
+  favoritesImported: boolean;
+  /** Subscribed market IDs in ascending order. */
+  marketIds: number[];
+  /** Followed subaccounts with enabled bells, encoded as bytes32. */
+  traderBells: Hex[];
+}
+
+/** Exactly one revision-guarded subscription operation; the SDK fills unused wire fields with null. */
+export type MobileNotificationSubscriptionsUpdate = {
+  /** Latest subscription revision, not the settings revision. */
+  expectedRevision: number;
+} & (
+  | {
+      /** Set a bell; enabling requires an existing follow relationship. */
+      traderBell: {
+        /** Target non-isolated subaccount belonging to another wallet. */
+        subaccount: Subaccount;
+        /** Desired bell state. */
+        enabled: boolean;
+      };
+      /** Cannot be combined with a trader bell operation. */
+      market?: never;
+      /** Cannot be combined with a trader bell operation. */
+      importMarkets?: never;
+    }
+  | {
+      /** Subscribe or unsubscribe one known market. */
+      market: {
+        /** Positive product ID. */
+        productId: number;
+        /** Desired subscription state. */
+        subscribed: boolean;
+      };
+      /** Cannot be combined with a market operation. */
+      traderBell?: never;
+      /** Cannot be combined with a market operation. */
+      importMarkets?: never;
+    }
+  | {
+      /** One-time merge of up to 500 local market IDs. */
+      importMarkets: number[];
+      /** Cannot be combined with an import operation. */
+      traderBell?: never;
+      /** Cannot be combined with an import operation. */
+      market?: never;
+    }
+);
+
+/** Allowlisted notification destination; never interpret it as an arbitrary URL. */
+export type MobileNotificationRoute =
+  | {
+      /** Public profile destination. */
+      name: 'profile';
+      /** Profile subaccount as bytes32. */
+      subaccount: Hex;
+    }
+  | {
+      /** Market destination. */
+      name: 'market';
+      /** Positive product ID. */
+      productId: number;
+    }
+  | {
+      /** Own portfolio destination. */
+      name: 'portfolio';
+    };
+
+/** V2 push/inbox navigation data, not a complete historical trade or notification body. */
+export interface MobileNotificationPayloadV2 {
+  /** Payload protocol version. */
+  payloadVersion: 2;
+  /** Logical notification UUID for click deduplication. */
+  notificationId: string;
+  /** Intended wallet; private navigation must wait for this wallet to connect. */
+  recipientWallet: Hex;
+  /** Registered notification type. */
+  typeId: MobileNotificationTypeId;
+  /** Supported template version. */
+  templateVersion: 1;
+  /** Named destination and its parameters. */
+  route: MobileNotificationRoute;
+}
+
+/** Accepted logical notification; does not prove device delivery or read status. */
+export interface MobileNotificationInboxItem {
+  /** Logical notification UUID. */
+  notificationId: string;
+  /** Registered notification type. */
+  typeId: MobileNotificationTypeId;
+  /** Navigation data, without title, body, or read state. */
+  data: MobileNotificationPayloadV2;
+  /** Intent acceptance time in milliseconds. */
+  createdAt: number;
+  /** Backend-computed trade attribution. */
+  tradeWithin24h: boolean;
+}
+
+/** Private notification page, ordered newest first. */
+export interface MobileNotificationInboxV2 {
+  /** Accepted intents owned by the signing wallet. */
+  notifications: MobileNotificationInboxItem[];
+  /** Pass unchanged to the next request, or null when pagination is complete. */
+  nextCursor: string | null;
+}
+
+/** Analytics event with the fields required by its interaction; unused wire fields are filled with null. */
+export type MobileProductEvent = {
+  /** Stable event UUID; reuse across retries. */
+  clientEventId: string;
+  /** Actual event time in milliseconds, within the past 7 days or next 5 minutes. */
+  occurredAt: number;
+} & (
+  | {
+      /** Notification open; not a read-state mutation. */
+      eventName: 'notif_opened';
+      /** Notification owned by the signing wallet. */
+      notificationId: string;
+      /** Not used for notification opens. */
+      productId?: never;
+      /** Not used for notification opens. */
+      query?: never;
+    }
+  | {
+      /** Market or chart interaction. */
+      eventName: 'market_viewed' | 'chart_opened';
+      /** Positive product ID. */
+      productId: number;
+      /** Not used for market/chart interactions. */
+      notificationId?: never;
+      /** Not used for market/chart interactions. */
+      query?: never;
+    }
+  | {
+      /** Search interaction. */
+      eventName: 'search';
+      /** Nonblank search query, at most 80 Unicode characters. */
+      query: string;
+      /** Not used for searches. */
+      notificationId?: never;
+      /** Not used for searches. */
+      productId?: never;
+    }
+);
+
 /**
  * Common params for signed requests that authenticate as a given subaccount.
  */
@@ -504,11 +714,8 @@ export type GetMobileFollowingParams = GetMobileFollowListParams;
 /**
  * Params for {@link MobileClient.registerExpoToken}.
  */
-export interface MobileRegisterExpoTokenParams extends MobileSignedRequestParams {
-  /**
-   * Expo push token, e.g. `ExponentPushToken[...]`.
-   */
-  expoToken: string;
+export interface MobileRegisterExpoTokenParams
+  extends MobileSignedRequestParams, MobileWithExpoTokenParams {
   platform: MobileNotificationPlatform;
   /**
    * BCP-47 locale tag, max 35 chars.
@@ -542,6 +749,67 @@ export type GetMobileNotificationPreferencesParams = MobileWithExpoTokenParams;
  */
 export type GetMobileRegisteredWalletParams = MobileWithExpoTokenParams;
 
+/**
+ * Params for {@link MobileClient.registerExpoTokenV2}.
+ */
+export interface MobileRegisterExpoTokenV2Params extends MobileRegisterExpoTokenParams {
+  /** Actual notification types and routes supported by this device. */
+  capabilities: MobileNotificationCapabilities;
+}
+
+/**
+ * Params for {@link MobileClient.getNotificationRegistrationV2}.
+ */
+export type GetMobileNotificationRegistrationV2Params =
+  MobileWithExpoTokenParams;
+
+/**
+ * Params for {@link MobileClient.getNotificationSettingsV2}.
+ */
+export type GetMobileNotificationSettingsV2Params = MobileWithExpoTokenParams;
+
+/**
+ * Params for {@link MobileClient.updateNotificationSettingsV2}.
+ */
+export interface MobileUpdateNotificationSettingsV2Params extends MobileWithExpoTokenParams {
+  /** Latest settings revision; stale values fail with 6203. */
+  expectedRevision: number;
+  /** Full replacement, not a partial patch. */
+  settings: MobileNotificationSettings;
+}
+
+/**
+ * Params for {@link MobileClient.getNotificationSubscriptions}; no Expo token is needed.
+ */
+export type GetMobileNotificationSubscriptionsParams =
+  MobileSignedRequestParams;
+
+/**
+ * Params for {@link MobileClient.updateNotificationSubscriptions}.
+ */
+export interface MobileUpdateNotificationSubscriptionsParams extends MobileSignedRequestParams {
+  /** Exactly one operation, with the latest subscription revision. */
+  update: MobileNotificationSubscriptionsUpdate;
+}
+
+/**
+ * Params for {@link MobileClient.getNotificationInboxV2}; no Expo token is needed.
+ */
+export interface GetMobileNotificationInboxV2Params extends MobileSignedRequestParams {
+  /** Previous nextCursor; omit or pass null for the first page. */
+  cursor?: string | null;
+  /** Page size from 1 to 50; omission/null uses the server default of 20. */
+  limit?: number | null;
+}
+
+/**
+ * Params for {@link MobileClient.recordProductEvents}.
+ */
+export interface MobileRecordProductEventsParams extends MobileSignedRequestParams {
+  /** One to fifty events, validated and committed atomically. */
+  events: MobileProductEvent[];
+}
+
 /** Official account-level 30-day PnL badge, independent of position PnL. */
 export interface MobileSocialFeedTraderBadge {
   /** Qualification tier. */
@@ -676,10 +944,39 @@ export interface MobileSocialFeedCommentPreview {
 
 /** Exposure requirements associated with a reading session. */
 export interface MobileSocialFeedViewTracking {
-  /** Required visible fraction. */
-  minVisibleRatio: number;
-  /** Required visible duration in milliseconds. */
-  minDurationMs: number;
+  /**
+   * Detail-visit exposure: report the primary detail target after it is shown in the foreground.
+   * List visible-ratio / dwell thresholds are no longer used.
+   */
+  mode: 'detail_visit';
+}
+
+/** Uploaded feed image metadata; bytes are fetched separately with the reading session. */
+export interface MobileSocialFeedImage {
+  /** Image UUID. */
+  imageId: string;
+  /** Backend path for the original image bytes. */
+  url: string;
+  /** Display-orientation width in pixels. */
+  width: number;
+  /** Display-orientation height in pixels. */
+  height: number;
+  /** Detected content type. */
+  contentType: 'image/jpeg' | 'image/png';
+  /** Original file size in bytes. */
+  byteSize: number;
+  /** Always-present thumbnail (longest edge ≤ 512, never upscaled). */
+  thumbnail: MobileSocialFeedImageThumbnail;
+}
+
+/** Thumbnail metadata for an uploaded feed image. */
+export interface MobileSocialFeedImageThumbnail {
+  /** Backend path for the thumbnail bytes. */
+  url: string;
+  /** Thumbnail width in pixels. */
+  width: number;
+  /** Thumbnail height in pixels. */
+  height: number;
 }
 
 /** Coverage of the candidate authors in a qualification snapshot. */
@@ -728,6 +1025,8 @@ export interface MobileSocialFeedItemBase {
 
 /** Content shared by authored posts and trade cards. */
 export interface MobileSocialFeedContentBase extends MobileSocialFeedItemBase {
+  /** Bound images in display order; empty when none. */
+  images: MobileSocialFeedImage[];
   /** Card text, empty for automatic cards. */
   text: string;
   /** Mentions in the original, unmodified text. */
@@ -802,13 +1101,13 @@ export type MobileSocialFeedItem =
   | MobileSocialFeedPost
   | MobileSocialFeedReply;
 
-/** Fixed-duration social feed reading session. Credentials and cursors must be returned unchanged. */
+/** Idle-renewed social feed reading session. Credentials and cursors must be returned unchanged. */
 export interface MobileSocialFeedReadSession {
   /** Session identifier. */
   sessionId: string;
   /** Feed, item, or full position history session. */
   mode: MobileSocialFeedReadSessionMode;
-  /** Fixed expiration time in Unix milliseconds; pagination does not extend it. */
+  /** Current idle expiration in Unix milliseconds; legitimate session requests renew it. */
   expiresAtMs: number;
   /** Visibility requirements for explicit exposure reporting. */
   viewTracking: MobileSocialFeedViewTracking;
@@ -976,6 +1275,12 @@ export type GetMobilePositionFeedParams = MobileSocialFeedListParams &
 export type GetMobileFeedItemParams = MobileSocialFeedReadParams & {
   /** Target item UUID. */
   itemId: string;
+  /**
+   * Detail-visit event UUID generated once per real navigation into this item.
+   * Reuse the same value on retries for the same visit; omit for prefetch.
+   * Registering the event does not increment the view count by itself.
+   */
+  viewEventId?: string;
   /** Preview size, 0–3. */
   commentPreviewLimit?: number;
   /** Existing session authorized for the item. */
@@ -1039,6 +1344,8 @@ export interface MobileSocialFeedPost extends MobileSocialFeedContentBase {
 export interface MobileSocialFeedReply extends MobileSocialFeedItemBase {
   /** Reply discriminant. */
   kind: 'reply';
+  /** Bound images in display order; empty when none. */
+  images: MobileSocialFeedImage[];
   /** Original text. */
   text: string;
   /** Mentions in the text. */
@@ -1285,6 +1592,42 @@ export interface MobileCreateFeedPostParams extends MobileSignedRequestParams {
   mentions: MobileSocialFeedMentionParams[];
   /** Original JSON text, at most 256 KiB UTF-8; never reformatted by the SDK. */
   drawingDataJson?: string;
+  /**
+   * Up to nine distinct ready image UUIDs owned by the signer, in display order.
+   * Omit or pass `[]` when none; order participates in the signature and idempotency hash.
+   * Images alone are not enough — nonblank text or a valid drawing is still required.
+   */
+  imageIds?: string[];
+}
+
+/**
+ * Direct multipart upload of one static JPEG/PNG (whole request ≤ 2 MiB including signature overhead).
+ * The SDK hashes the bytes as Keccak256 for signing; the service verifies the received file matches.
+ */
+export interface MobileCreateFeedImageUploadParams extends MobileSignedRequestParams {
+  /** Raw original file bytes; format is validated by the service. */
+  fileBytes: Uint8Array;
+}
+
+/** Parameters for preparing a protected feed image request with a reading session. */
+export interface GetMobileFeedImageRequestParams {
+  /** Backend path from {@link MobileSocialFeedImage.url} or thumbnail.url. */
+  path: string;
+  /** Reading session that fully delivered the parent item. */
+  sessionId: string;
+  /** Browser credential for that session. */
+  viewerToken: string;
+}
+
+/** Parameters for fetching protected feed image bytes with a reading session. */
+export type GetMobileFeedImageBytesParams = GetMobileFeedImageRequestParams;
+
+/** URL and authentication headers for native image components or direct image reads. */
+export interface MobileFeedImageRequest {
+  /** Absolute image URL; pass as the native image source URI. */
+  url: string;
+  /** Original reading-session credentials required to access the image. */
+  headers: Record<string, string>;
 }
 
 /** Parameters for first adding or replacing a drawing. Writes must be serialized by the caller. */
@@ -1331,6 +1674,11 @@ export interface MobileCreateFeedCommentParams extends MobileSignedRequestParams
   mentions: MobileSocialFeedMentionParams[];
   /** Position still held by the signed author; invalid attachment rejects the whole request. */
   attachedPositionId?: string;
+  /**
+   * Up to nine distinct ready image UUIDs owned by the signer, in display order.
+   * Omit or pass `[]` when none; images cannot replace the required nonblank text.
+   */
+  imageIds?: string[];
 }
 
 /** Parameters for setting or cancelling a signed user's like. */
@@ -1341,14 +1689,22 @@ export interface MobileSetFeedLikeParams extends MobileSignedRequestParams {
   isLiked: boolean;
 }
 
-/** Unsigned exposure report; only send after satisfying the session's viewTracking requirements. */
+/**
+ * Unsigned detail-visit report. Call after the primary detail target is shown in the foreground,
+ * using the same {@link GetMobileFeedItemParams.viewEventId} previously sent to `getFeedItem`.
+ */
 export interface MobileRecordFeedViewsParams {
-  /** Original reading session. */
+  /** Original reading session returned by the detail read. */
   sessionId: string;
-  /** Original opaque browsing credential. */
+  /** Original opaque browsing credential from that read session. */
   viewerToken: string;
-  /** One to fifty fully delivered, readable, interactive item UUIDs. */
-  itemIds: string[];
+  /**
+   * Detail-visit event UUID registered on the preceding feed_item call.
+   * Reuse across retries for the same visit; generate a new UUID only after leaving and re-entering.
+   */
+  viewEventId: string;
+  /** Exactly one fully delivered, readable detail-target item UUID. */
+  itemId: string;
 }
 
 /** Parameters for full position history, not just published feed items. */

package/src/types/index.ts

@@ -2,6 +2,7 @@ export * from './clientTypes';
 export * from './mobileErrorCodes';
 export * from './MobileServerFailureError';
 export * from './MobileUnsupportedFeedItemError';
+export * from './MobileUnsupportedNotificationRouteError';
 export * from './serverBaseTypes';
 export * from './serverExecuteTypes';
 export * from './serverModelTypes';

package/src/types/mobileErrorCodes.ts

@@ -44,6 +44,12 @@ export const MOBILE_ERROR_CODES = {
   INVALID_EXPO_TOKEN: 6200,
   INVALID_DEVICE_METADATA: 6201,
   INVALID_PREFERENCES: 6202,
+  /** Settings or subscription revision is stale. Read the resource again before retrying. */
+  NOTIFICATION_REVISION_CONFLICT: 6203,
+  /** Invalid subscription operation, inbox parameters, event batch, timestamp, or notification ownership. */
+  INVALID_NOTIFICATION_REQUEST: 6204,
+  /** Wallet already has the maximum number of active device registrations. */
+  NOTIFICATION_DEVICE_LIMIT: 6205,
   /** 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. */
@@ -88,6 +94,10 @@ export const MOBILE_ERROR_CODES = {
   EMPTY_SOCIAL_FEED_CONTENT: 6323,
   /** Feed reads are only available through public_query. */
   SOCIAL_FEED_QUERY_REMOVED: 6325,
+  /** Image format, dimensions, integrity, ownership, readiness, expiry, hash, or count is invalid. */
+  INVALID_SOCIAL_FEED_IMAGE: 6326,
+  /** An existing detail-visit event was reused with a different item or browsing credential. */
+  SOCIAL_FEED_VIEW_EVENT_REBOUND: 6327,
 } as const;
 
 /**

package/src/types/serverExecuteTypes.ts

@@ -6,9 +6,11 @@ import {
 import {
   MobileServerSocialFeedAuthor,
   MobileServerSocialFeedDrawing,
+  MobileServerSocialFeedImage,
   MobileServerSocialFeedItem,
   MobileServerSocialFeedReply,
 } from './serverModelTypes';
+import { MobileServerNotificationSettingsV2Response } from './serverQueryTypes';
 import {
   MobileServerExecuteRequestType,
   MobileServerPublicExecuteRequestByType,
@@ -80,15 +82,31 @@ export interface MobileServerAvatarUploadResponse {
   expires_in_seconds: number;
 }
 
+/** Ready image returned by a direct multipart upload. */
+export interface MobileServerSocialFeedImageUploadResponse {
+  /** Ready image metadata, including original and thumbnail paths. */
+  image: MobileServerSocialFeedImage;
+}
+
 /**
  * Success payloads for each signed `execute`, keyed by request `type`. Mutations return either the success
  * envelope alone or authoritative post-commit state; avatar upload creation returns a temporary grant.
  */
 export interface MobileServerExecuteResponseByType {
+  /** Capability-aware device registration returns only status. */
+  register_expo_token_v2: MobileServerEmptyExecuteResponse;
+  /** Re-query subscriptions after success to obtain the new revision. */
+  update_notification_subscriptions: MobileServerEmptyExecuteResponse;
+  /** Atomic event recording returns only status. */
+  record_product_events: MobileServerEmptyExecuteResponse;
   /** Published or idempotently recovered item. */
   create_feed_post: MobileServerSocialFeedPostResponse;
   /** Atomically published reply and updated count. */
   create_feed_comment: MobileServerSocialFeedCommentResponse;
+  /** Direct post-image upload; the image is ready immediately. */
+  create_feed_post_image_uploads: MobileServerSocialFeedImageUploadResponse;
+  /** Direct comment-image upload; the image is ready immediately. */
+  create_feed_comment_image_uploads: MobileServerSocialFeedImageUploadResponse;
   /** First attached drawing. */
   create_feed_chart_drawing: MobileServerSocialFeedDrawingMutationResponse;
   /** Replaced or idempotently recovered drawing. */
@@ -181,6 +199,8 @@ export interface MobileServerSocialFeedPresenceResponse {
 
 /** Response payloads for unsigned writes. */
 export interface MobileServerPublicExecuteResponseByType {
+  /** Saved document, including the advanced settings revision. */
+  update_notification_settings_v2: MobileServerNotificationSettingsV2Response;
   /** Token removal returns only the success envelope. */
   unregister_expo_token: MobileServerEmptyExecuteResponse;
   /** Preference updates return only the success envelope. */