@metamask-previews/core-backend 12.3.0-preview-9fd631f7d → 12.3.0-preview-6fbab7311

package/CHANGELOG.md

@@ -9,14 +9,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- Add `LaunchpadTokenDetailsService` for real-time launchpad token detail streaming over the shared backend WebSocket, exposing `subscribe`/`unsubscribe` by `assetId` and publishing `tokenUpdated`, `statusChanged`, and `subscriptionError` events, along with `LAUNCHPAD_TDP_SERVICE_ALLOWED_ACTIONS`/`LAUNCHPAD_TDP_SERVICE_ALLOWED_EVENTS` and launchpad event types/normalizers (`parseBatch`, `normalizeEvent`, `buildChannel`) ([#10884](https://github.com/MetaMask/core/pull/10884))
+- Add `ChannelSubscriptionManager`, a reusable per-channel WebSocket subscription lifecycle helper (reference counting, grace-period unsubscribe, unsubscribe retry, and resubscribe on reconnect) shared by `OHLCVService` and `LaunchpadTokenDetailsService` ([#10884](https://github.com/MetaMask/core/pull/10884))
 - Add support for Node.js 26 ([#10981](https://github.com/MetaMask/core/pull/10981))
 
 ### Changed
 
+- **BREAKING:** Remove the unused `BackendWebSocketService:getConnectionInfo` and `BackendWebSocketService:findSubscriptionsByChannelPrefix` actions from `OHLCV_SERVICE_ALLOWED_ACTIONS` ([#10884](https://github.com/MetaMask/core/pull/10884))
+  - `OHLCV_SERVICE_ALLOWED_ACTIONS` / `OHLCV_SERVICE_ALLOWED_EVENTS` and `LAUNCHPAD_TDP_SERVICE_ALLOWED_ACTIONS` / `LAUNCHPAD_TDP_SERVICE_ALLOWED_EVENTS` are now sourced from a single shared set (the `BackendWebSocketService` actions/events the `ChannelSubscriptionManager` actually calls), so both services grant identical, minimal permissions.
+  - If you build the `OHLCVService` restricted messenger from `OHLCV_SERVICE_ALLOWED_ACTIONS`, it will no longer be granted those two actions. Neither action was ever called by `OHLCVService`, so no runtime behavior changes; grant them explicitly only if your own code calls them through that messenger.
+- Refactor `OHLCVService` to delegate its subscription lifecycle to the shared `ChannelSubscriptionManager` via composition, with no change to its public methods or published events ([#10884](https://github.com/MetaMask/core/pull/10884))
 - Stop publishing the `api/test-utils` test helper, which was never reachable through the package's `exports` field ([#10916](https://github.com/MetaMask/core/pull/10916))
 - Bump `@metamask/account-tree-controller` from `^11.0.1` to `^11.2.0` ([#10891](https://github.com/MetaMask/core/pull/10891), [#10925](https://github.com/MetaMask/core/pull/10925), [#11092](https://github.com/MetaMask/core/pull/11092))
 - Bump `@metamask/profile-sync-controller` from `^34.0.3` to `^36.0.0` ([#10905](https://github.com/MetaMask/core/pull/10905), [#10925](https://github.com/MetaMask/core/pull/10925), [#11092](https://github.com/MetaMask/core/pull/11092))
 - Bump `@metamask/utils` from `^12.0.0` to `^12.0.1` ([#11107](https://github.com/MetaMask/core/pull/11107))
+- Bump `uuid` from `^11.1.1` to `^14.0.0` ([#10941](https://github.com/MetaMask/core/pull/10941))
 
 ## [12.3.0]
 

package/dist/index.d.ts

@@ -7,6 +7,10 @@ export { ApiPlatformClientService, apiPlatformClientServiceName, } from './ApiPl
 export type { ApiPlatformClientServiceOptions, ApiPlatformClientServiceActions, ApiPlatformClientServiceEvents, ApiPlatformClientServiceMessenger, } from './ApiPlatformClientService.js';
 export { OHLCVService, OHLCV_SERVICE_ALLOWED_ACTIONS, OHLCV_SERVICE_ALLOWED_EVENTS, } from './ws/ohlcv/index.js';
 export type { OHLCVBar, OHLCVSubscriptionOptions, OHLCVSystemNotificationData, OHLCVServiceOptions, OHLCVServiceActions, OHLCVServiceAllowedActions, OHLCVServiceBarUpdatedEvent, OHLCVServiceChainStatusChangedEvent, OHLCVServiceSubscriptionErrorEvent, OHLCVServiceEvents, OHLCVServiceAllowedEvents, OHLCVServiceMessenger, } from './ws/ohlcv/index.js';
+export { ChannelSubscriptionManager } from './ws/ChannelSubscriptionManager.js';
+export type { ChannelSubscriptionManagerMessenger, ChannelSubscriptionManagerOptions, ChannelSubscriptionOperation, } from './ws/ChannelSubscriptionManager.js';
+export { LaunchpadTokenDetailsService, LAUNCHPAD_TDP_SERVICE_ALLOWED_ACTIONS, LAUNCHPAD_TDP_SERVICE_ALLOWED_EVENTS, buildChannel, normalizeEvent, parseBatch, LAUNCHPAD_SUBSCRIPTION_NAMESPACE, } from './ws/launchpad/index.js';
+export type { LaunchpadSystemNotificationData, LaunchpadTokenDetailsServiceOptions, LaunchpadTokenDetailsServiceActions, LaunchpadTokenDetailsServiceAllowedActions, LaunchpadTokenDetailsServiceTokenUpdatedEvent, LaunchpadTokenDetailsServiceStatusChangedEvent, LaunchpadTokenDetailsServiceSubscriptionErrorEvent, LaunchpadTokenDetailsServiceEvents, LaunchpadTokenDetailsServiceAllowedEvents, LaunchpadTokenDetailsServiceMessenger, LaunchpadEventType, RawLaunchpadTokenEvent, LaunchpadTokenCreatedEvent, LaunchpadTokenStatsEvent, LaunchpadTokenMigratedEvent, LaunchpadTokenEvent, LaunchpadTokenDetailsSubscriptionOptions, } from './ws/launchpad/index.js';
 export { ApiPlatformClient, createApiPlatformClient, AccountsApiClient, PricesApiClient, TokenApiClient, TokensApiClient, API_URLS, STALE_TIMES, GC_TIMES, V6_DEFI_POSITION_TYPES, calculateRetryDelay, getQueryOptionsOverrides, shouldRetry, HttpError, } from './api/index.js';
 export type { ApiPlatformClientOptions, ApiUrls, FetchOptions, PageInfo, SupportedCurrency, MarketDataDetails, V5BalanceItem, V5BalancesResponse, V2BalanceItem, V2BalancesResponse, V4BalancesResponse, V6VsCurrency, V6DeFiPositionType, V6BalanceMetadata, V6StellarTokenBalanceMetadata, V6TokenBalanceMetadata, V6BalanceItem, V6BalancesResponse, V1SupportedNetworksResponse, V2SupportedNetworksResponse, V2ActiveNetworksResponse, V1TransactionByHashResponse, V1AccountTransactionsResponse, V4MultiAccountTransactionsResponse, ValueTransfer, V1AccountRelationshipResult, NftItem, V2NftsResponse, TokenDiscoveryItem, V2TokensResponse, V3SpotPricesResponse, CoinGeckoSpotPrice, ExchangeRateInfo, V1ExchangeRatesResponse, PriceSupportedNetworksResponse, PriceV1SupportedNetworksResponse, PriceV2SupportedNetworksResponse, V1HistoricalPricesResponse, V3HistoricalPricesResponse, TokenMetadata, TokenListQueryOptions, TokenV2SupportedNetworksResponse, V1TokenDescriptionResponse, NetworkInfo, TopAsset, TrendingSortBy, TrendingToken, TopGainersSortOption, TrendingSortOption, V1SuggestedOccurrenceFloorsResponse, V1TokenSupportedNetworksResponse, V2TokenSupportedNetworksResponse, V3AssetResponse, } from './api/index.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AAEzC,YAAY,EACV,8BAA8B,EAC9B,oBAAoB,EACpB,qBAAqB,EACrB,yBAAyB,EACzB,gBAAgB,EAChB,eAAe,EACf,qBAAqB,EACrB,uBAAuB,EACvB,8BAA8B,EAC9B,kDAAkD,EAClD,6BAA6B,EAC7B,gCAAgC,GACjC,MAAM,iCAAiC,CAAC;AAMzC,OAAO,EACL,sBAAsB,EACtB,wCAAwC,EACxC,uCAAuC,GACxC,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,sBAAsB,EACtB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,EAC7B,cAAc,IAAI,oCAAoC,EACtD,6CAA6C,EAC7C,yCAAyC,EACzC,4CAA4C,EAC5C,wCAAwC,EACxC,4BAA4B,EAC5B,aAAa,IAAI,mCAAmC,EACpD,+BAA+B,GAChC,MAAM,gCAAgC,CAAC;AAMxC,YAAY,EACV,WAAW,EACX,KAAK,EACL,OAAO,EACP,QAAQ,EACR,aAAa,EACb,sBAAsB,GACvB,MAAM,YAAY,CAAC;AAMpB,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AAEvC,YAAY,EACV,+BAA+B,EAC/B,+BAA+B,EAC/B,8BAA8B,EAC9B,iCAAiC,GAClC,MAAM,+BAA+B,CAAC;AAMvC,OAAO,EACL,YAAY,EACZ,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAE7B,YAAY,EACV,QAAQ,EACR,wBAAwB,EACxB,2BAA2B,EAC3B,mBAAmB,EACnB,mBAAmB,EACnB,0BAA0B,EAC1B,2BAA2B,EAC3B,mCAAmC,EACnC,kCAAkC,EAClC,kBAAkB,EAClB,yBAAyB,EACzB,qBAAqB,GACtB,MAAM,qBAAqB,CAAC;AAM7B,OAAO,EACL,iBAAiB,EACjB,uBAAuB,EAEvB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,eAAe,EAEf,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,sBAAsB,EAEtB,mBAAmB,EACnB,wBAAwB,EACxB,WAAW,EAEX,SAAS,GACV,MAAM,gBAAgB,CAAC;AAMxB,YAAY,EAEV,wBAAwB,EACxB,OAAO,EACP,YAAY,EAEZ,QAAQ,EACR,iBAAiB,EACjB,iBAAiB,EAEjB,aAAa,EACb,kBAAkB,EAClB,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,YAAY,EACZ,kBAAkB,EAClB,iBAAiB,EACjB,6BAA6B,EAC7B,sBAAsB,EACtB,aAAa,EACb,kBAAkB,EAClB,2BAA2B,EAC3B,2BAA2B,EAC3B,wBAAwB,EACxB,2BAA2B,EAC3B,6BAA6B,EAC7B,kCAAkC,EAClC,aAAa,EACb,2BAA2B,EAC3B,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,gBAAgB,EAEhB,oBAAoB,EACpB,kBAAkB,EAClB,gBAAgB,EAChB,uBAAuB,EACvB,8BAA8B,EAC9B,gCAAgC,EAChC,gCAAgC,EAChC,0BAA0B,EAC1B,0BAA0B,EAE1B,aAAa,EACb,qBAAqB,EACrB,gCAAgC,EAChC,0BAA0B,EAC1B,WAAW,EACX,QAAQ,EACR,cAAc,EACd,aAAa,EACb,oBAAoB,EACpB,kBAAkB,EAClB,mCAAmC,EAEnC,gCAAgC,EAChC,gCAAgC,EAChC,eAAe,GAChB,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -16,6 +16,14 @@ export { ApiPlatformClientService, apiPlatformClientServiceName, } from './ApiPl
 // ============================================================================
 export { OHLCVService, OHLCV_SERVICE_ALLOWED_ACTIONS, OHLCV_SERVICE_ALLOWED_EVENTS, } from './ws/ohlcv/index.js';
 // ============================================================================
+// CHANNEL SUBSCRIPTION MANAGER
+// ============================================================================
+export { ChannelSubscriptionManager } from './ws/ChannelSubscriptionManager.js';
+// ============================================================================
+// LAUNCHPAD TOKEN DETAILS SERVICE
+// ============================================================================
+export { LaunchpadTokenDetailsService, LAUNCHPAD_TDP_SERVICE_ALLOWED_ACTIONS, LAUNCHPAD_TDP_SERVICE_ALLOWED_EVENTS, buildChannel, normalizeEvent, parseBatch, LAUNCHPAD_SUBSCRIPTION_NAMESPACE, } from './ws/launchpad/index.js';
+// ============================================================================
 // API PLATFORM CLIENT
 // ============================================================================
 export { ApiPlatformClient, createApiPlatformClient, 

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAE/B,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AAiBzC,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,wCAAwC,EACxC,uCAAuC,GACxC,MAAM,gCAAgC,CAAC;AA8BxC,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AASvC,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,OAAO,EACL,YAAY,EACZ,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAiB7B,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EACL,iBAAiB,EACjB,uBAAuB;AACvB,yBAAyB;AACzB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,eAAe;AACf,YAAY;AACZ,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,sBAAsB;AACtB,UAAU;AACV,mBAAmB,EACnB,wBAAwB,EACxB,WAAW;AACX,SAAS;AACT,SAAS,GACV,MAAM,gBAAgB,CAAC","sourcesContent":["// Core Backend Package Exports\n\n// ============================================================================\n// BACKEND WEBSOCKET SERVICE\n// ============================================================================\n\nexport {\n  BackendWebSocketService,\n  getCloseReason,\n  WebSocketState,\n  WebSocketEventType,\n} from './ws/BackendWebSocketService.js';\n\nexport type {\n  BackendWebSocketServiceOptions,\n  ClientRequestMessage,\n  ServerResponseMessage,\n  ServerNotificationMessage,\n  WebSocketMessage,\n  ChannelCallback,\n  WebSocketSubscription,\n  WebSocketConnectionInfo,\n  BackendWebSocketServiceActions,\n  BackendWebSocketServiceConnectionStateChangedEvent,\n  BackendWebSocketServiceEvents,\n  BackendWebSocketServiceMessenger,\n} from './ws/BackendWebSocketService.js';\n\n// ============================================================================\n// ACCOUNT ACTIVITY SERVICE\n// ============================================================================\n\nexport {\n  AccountActivityService,\n  ACCOUNT_ACTIVITY_SERVICE_ALLOWED_ACTIONS,\n  ACCOUNT_ACTIVITY_SERVICE_ALLOWED_EVENTS,\n} from './ws/AccountActivityService.js';\n\nexport type {\n  SystemNotificationData,\n  SubscriptionOptions,\n  AccountActivityServiceOptions,\n  AccountActivityServiceActions,\n  AllowedActions as AccountActivityServiceAllowedActions,\n  AccountActivityServiceTransactionUpdatedEvent,\n  AccountActivityServiceBalanceUpdatedEvent,\n  AccountActivityServiceSubscriptionErrorEvent,\n  AccountActivityServiceStatusChangedEvent,\n  AccountActivityServiceEvents,\n  AllowedEvents as AccountActivityServiceAllowedEvents,\n  AccountActivityServiceMessenger,\n} from './ws/AccountActivityService.js';\n\n// ============================================================================\n// SHARED TYPES\n// ============================================================================\n\nexport type {\n  Transaction,\n  Asset,\n  Balance,\n  Transfer,\n  BalanceUpdate,\n  AccountActivityMessage,\n} from './types.js';\n\n// ============================================================================\n// API PLATFORM CLIENT SERVICE\n// ============================================================================\n\nexport {\n  ApiPlatformClientService,\n  apiPlatformClientServiceName,\n} from './ApiPlatformClientService.js';\n\nexport type {\n  ApiPlatformClientServiceOptions,\n  ApiPlatformClientServiceActions,\n  ApiPlatformClientServiceEvents,\n  ApiPlatformClientServiceMessenger,\n} from './ApiPlatformClientService.js';\n\n// ============================================================================\n// OHLCV SERVICE\n// ============================================================================\n\nexport {\n  OHLCVService,\n  OHLCV_SERVICE_ALLOWED_ACTIONS,\n  OHLCV_SERVICE_ALLOWED_EVENTS,\n} from './ws/ohlcv/index.js';\n\nexport type {\n  OHLCVBar,\n  OHLCVSubscriptionOptions,\n  OHLCVSystemNotificationData,\n  OHLCVServiceOptions,\n  OHLCVServiceActions,\n  OHLCVServiceAllowedActions,\n  OHLCVServiceBarUpdatedEvent,\n  OHLCVServiceChainStatusChangedEvent,\n  OHLCVServiceSubscriptionErrorEvent,\n  OHLCVServiceEvents,\n  OHLCVServiceAllowedEvents,\n  OHLCVServiceMessenger,\n} from './ws/ohlcv/index.js';\n\n// ============================================================================\n// API PLATFORM CLIENT\n// ============================================================================\n\nexport {\n  ApiPlatformClient,\n  createApiPlatformClient,\n  // Individual API clients\n  AccountsApiClient,\n  PricesApiClient,\n  TokenApiClient,\n  TokensApiClient,\n  // Constants\n  API_URLS,\n  STALE_TIMES,\n  GC_TIMES,\n  V6_DEFI_POSITION_TYPES,\n  // Helpers\n  calculateRetryDelay,\n  getQueryOptionsOverrides,\n  shouldRetry,\n  // Errors\n  HttpError,\n} from './api/index.js';\n\n// ============================================================================\n// API PLATFORM CLIENT TYPES\n// ============================================================================\n\nexport type {\n  // Client options\n  ApiPlatformClientOptions,\n  ApiUrls,\n  FetchOptions,\n  // Shared types\n  PageInfo,\n  SupportedCurrency,\n  MarketDataDetails,\n  // Accounts API types\n  V5BalanceItem,\n  V5BalancesResponse,\n  V2BalanceItem,\n  V2BalancesResponse,\n  V4BalancesResponse,\n  V6VsCurrency,\n  V6DeFiPositionType,\n  V6BalanceMetadata,\n  V6StellarTokenBalanceMetadata,\n  V6TokenBalanceMetadata,\n  V6BalanceItem,\n  V6BalancesResponse,\n  V1SupportedNetworksResponse,\n  V2SupportedNetworksResponse,\n  V2ActiveNetworksResponse,\n  V1TransactionByHashResponse,\n  V1AccountTransactionsResponse,\n  V4MultiAccountTransactionsResponse,\n  ValueTransfer,\n  V1AccountRelationshipResult,\n  NftItem,\n  V2NftsResponse,\n  TokenDiscoveryItem,\n  V2TokensResponse,\n  // Prices API types\n  V3SpotPricesResponse,\n  CoinGeckoSpotPrice,\n  ExchangeRateInfo,\n  V1ExchangeRatesResponse,\n  PriceSupportedNetworksResponse,\n  PriceV1SupportedNetworksResponse,\n  PriceV2SupportedNetworksResponse,\n  V1HistoricalPricesResponse,\n  V3HistoricalPricesResponse,\n  // Token API types\n  TokenMetadata,\n  TokenListQueryOptions,\n  TokenV2SupportedNetworksResponse,\n  V1TokenDescriptionResponse,\n  NetworkInfo,\n  TopAsset,\n  TrendingSortBy,\n  TrendingToken,\n  TopGainersSortOption,\n  TrendingSortOption,\n  V1SuggestedOccurrenceFloorsResponse,\n  // Tokens API types\n  V1TokenSupportedNetworksResponse,\n  V2TokenSupportedNetworksResponse,\n  V3AssetResponse,\n} from './api/index.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+BAA+B;AAE/B,+EAA+E;AAC/E,4BAA4B;AAC5B,+EAA+E;AAE/E,OAAO,EACL,uBAAuB,EACvB,cAAc,EACd,cAAc,EACd,kBAAkB,GACnB,MAAM,iCAAiC,CAAC;AAiBzC,+EAA+E;AAC/E,2BAA2B;AAC3B,+EAA+E;AAE/E,OAAO,EACL,sBAAsB,EACtB,wCAAwC,EACxC,uCAAuC,GACxC,MAAM,gCAAgC,CAAC;AA8BxC,+EAA+E;AAC/E,8BAA8B;AAC9B,+EAA+E;AAE/E,OAAO,EACL,wBAAwB,EACxB,4BAA4B,GAC7B,MAAM,+BAA+B,CAAC;AASvC,+EAA+E;AAC/E,gBAAgB;AAChB,+EAA+E;AAE/E,OAAO,EACL,YAAY,EACZ,6BAA6B,EAC7B,4BAA4B,GAC7B,MAAM,qBAAqB,CAAC;AAiB7B,+EAA+E;AAC/E,+BAA+B;AAC/B,+EAA+E;AAE/E,OAAO,EAAE,0BAA0B,EAAE,MAAM,oCAAoC,CAAC;AAQhF,+EAA+E;AAC/E,kCAAkC;AAClC,+EAA+E;AAE/E,OAAO,EACL,4BAA4B,EAC5B,qCAAqC,EACrC,oCAAoC,EACpC,YAAY,EACZ,cAAc,EACd,UAAU,EACV,gCAAgC,GACjC,MAAM,yBAAyB,CAAC;AAsBjC,+EAA+E;AAC/E,sBAAsB;AACtB,+EAA+E;AAE/E,OAAO,EACL,iBAAiB,EACjB,uBAAuB;AACvB,yBAAyB;AACzB,iBAAiB,EACjB,eAAe,EACf,cAAc,EACd,eAAe;AACf,YAAY;AACZ,QAAQ,EACR,WAAW,EACX,QAAQ,EACR,sBAAsB;AACtB,UAAU;AACV,mBAAmB,EACnB,wBAAwB,EACxB,WAAW;AACX,SAAS;AACT,SAAS,GACV,MAAM,gBAAgB,CAAC","sourcesContent":["// Core Backend Package Exports\n\n// ============================================================================\n// BACKEND WEBSOCKET SERVICE\n// ============================================================================\n\nexport {\n  BackendWebSocketService,\n  getCloseReason,\n  WebSocketState,\n  WebSocketEventType,\n} from './ws/BackendWebSocketService.js';\n\nexport type {\n  BackendWebSocketServiceOptions,\n  ClientRequestMessage,\n  ServerResponseMessage,\n  ServerNotificationMessage,\n  WebSocketMessage,\n  ChannelCallback,\n  WebSocketSubscription,\n  WebSocketConnectionInfo,\n  BackendWebSocketServiceActions,\n  BackendWebSocketServiceConnectionStateChangedEvent,\n  BackendWebSocketServiceEvents,\n  BackendWebSocketServiceMessenger,\n} from './ws/BackendWebSocketService.js';\n\n// ============================================================================\n// ACCOUNT ACTIVITY SERVICE\n// ============================================================================\n\nexport {\n  AccountActivityService,\n  ACCOUNT_ACTIVITY_SERVICE_ALLOWED_ACTIONS,\n  ACCOUNT_ACTIVITY_SERVICE_ALLOWED_EVENTS,\n} from './ws/AccountActivityService.js';\n\nexport type {\n  SystemNotificationData,\n  SubscriptionOptions,\n  AccountActivityServiceOptions,\n  AccountActivityServiceActions,\n  AllowedActions as AccountActivityServiceAllowedActions,\n  AccountActivityServiceTransactionUpdatedEvent,\n  AccountActivityServiceBalanceUpdatedEvent,\n  AccountActivityServiceSubscriptionErrorEvent,\n  AccountActivityServiceStatusChangedEvent,\n  AccountActivityServiceEvents,\n  AllowedEvents as AccountActivityServiceAllowedEvents,\n  AccountActivityServiceMessenger,\n} from './ws/AccountActivityService.js';\n\n// ============================================================================\n// SHARED TYPES\n// ============================================================================\n\nexport type {\n  Transaction,\n  Asset,\n  Balance,\n  Transfer,\n  BalanceUpdate,\n  AccountActivityMessage,\n} from './types.js';\n\n// ============================================================================\n// API PLATFORM CLIENT SERVICE\n// ============================================================================\n\nexport {\n  ApiPlatformClientService,\n  apiPlatformClientServiceName,\n} from './ApiPlatformClientService.js';\n\nexport type {\n  ApiPlatformClientServiceOptions,\n  ApiPlatformClientServiceActions,\n  ApiPlatformClientServiceEvents,\n  ApiPlatformClientServiceMessenger,\n} from './ApiPlatformClientService.js';\n\n// ============================================================================\n// OHLCV SERVICE\n// ============================================================================\n\nexport {\n  OHLCVService,\n  OHLCV_SERVICE_ALLOWED_ACTIONS,\n  OHLCV_SERVICE_ALLOWED_EVENTS,\n} from './ws/ohlcv/index.js';\n\nexport type {\n  OHLCVBar,\n  OHLCVSubscriptionOptions,\n  OHLCVSystemNotificationData,\n  OHLCVServiceOptions,\n  OHLCVServiceActions,\n  OHLCVServiceAllowedActions,\n  OHLCVServiceBarUpdatedEvent,\n  OHLCVServiceChainStatusChangedEvent,\n  OHLCVServiceSubscriptionErrorEvent,\n  OHLCVServiceEvents,\n  OHLCVServiceAllowedEvents,\n  OHLCVServiceMessenger,\n} from './ws/ohlcv/index.js';\n\n// ============================================================================\n// CHANNEL SUBSCRIPTION MANAGER\n// ============================================================================\n\nexport { ChannelSubscriptionManager } from './ws/ChannelSubscriptionManager.js';\n\nexport type {\n  ChannelSubscriptionManagerMessenger,\n  ChannelSubscriptionManagerOptions,\n  ChannelSubscriptionOperation,\n} from './ws/ChannelSubscriptionManager.js';\n\n// ============================================================================\n// LAUNCHPAD TOKEN DETAILS SERVICE\n// ============================================================================\n\nexport {\n  LaunchpadTokenDetailsService,\n  LAUNCHPAD_TDP_SERVICE_ALLOWED_ACTIONS,\n  LAUNCHPAD_TDP_SERVICE_ALLOWED_EVENTS,\n  buildChannel,\n  normalizeEvent,\n  parseBatch,\n  LAUNCHPAD_SUBSCRIPTION_NAMESPACE,\n} from './ws/launchpad/index.js';\n\nexport type {\n  LaunchpadSystemNotificationData,\n  LaunchpadTokenDetailsServiceOptions,\n  LaunchpadTokenDetailsServiceActions,\n  LaunchpadTokenDetailsServiceAllowedActions,\n  LaunchpadTokenDetailsServiceTokenUpdatedEvent,\n  LaunchpadTokenDetailsServiceStatusChangedEvent,\n  LaunchpadTokenDetailsServiceSubscriptionErrorEvent,\n  LaunchpadTokenDetailsServiceEvents,\n  LaunchpadTokenDetailsServiceAllowedEvents,\n  LaunchpadTokenDetailsServiceMessenger,\n  LaunchpadEventType,\n  RawLaunchpadTokenEvent,\n  LaunchpadTokenCreatedEvent,\n  LaunchpadTokenStatsEvent,\n  LaunchpadTokenMigratedEvent,\n  LaunchpadTokenEvent,\n  LaunchpadTokenDetailsSubscriptionOptions,\n} from './ws/launchpad/index.js';\n\n// ============================================================================\n// API PLATFORM CLIENT\n// ============================================================================\n\nexport {\n  ApiPlatformClient,\n  createApiPlatformClient,\n  // Individual API clients\n  AccountsApiClient,\n  PricesApiClient,\n  TokenApiClient,\n  TokensApiClient,\n  // Constants\n  API_URLS,\n  STALE_TIMES,\n  GC_TIMES,\n  V6_DEFI_POSITION_TYPES,\n  // Helpers\n  calculateRetryDelay,\n  getQueryOptionsOverrides,\n  shouldRetry,\n  // Errors\n  HttpError,\n} from './api/index.js';\n\n// ============================================================================\n// API PLATFORM CLIENT TYPES\n// ============================================================================\n\nexport type {\n  // Client options\n  ApiPlatformClientOptions,\n  ApiUrls,\n  FetchOptions,\n  // Shared types\n  PageInfo,\n  SupportedCurrency,\n  MarketDataDetails,\n  // Accounts API types\n  V5BalanceItem,\n  V5BalancesResponse,\n  V2BalanceItem,\n  V2BalancesResponse,\n  V4BalancesResponse,\n  V6VsCurrency,\n  V6DeFiPositionType,\n  V6BalanceMetadata,\n  V6StellarTokenBalanceMetadata,\n  V6TokenBalanceMetadata,\n  V6BalanceItem,\n  V6BalancesResponse,\n  V1SupportedNetworksResponse,\n  V2SupportedNetworksResponse,\n  V2ActiveNetworksResponse,\n  V1TransactionByHashResponse,\n  V1AccountTransactionsResponse,\n  V4MultiAccountTransactionsResponse,\n  ValueTransfer,\n  V1AccountRelationshipResult,\n  NftItem,\n  V2NftsResponse,\n  TokenDiscoveryItem,\n  V2TokensResponse,\n  // Prices API types\n  V3SpotPricesResponse,\n  CoinGeckoSpotPrice,\n  ExchangeRateInfo,\n  V1ExchangeRatesResponse,\n  PriceSupportedNetworksResponse,\n  PriceV1SupportedNetworksResponse,\n  PriceV2SupportedNetworksResponse,\n  V1HistoricalPricesResponse,\n  V3HistoricalPricesResponse,\n  // Token API types\n  TokenMetadata,\n  TokenListQueryOptions,\n  TokenV2SupportedNetworksResponse,\n  V1TokenDescriptionResponse,\n  NetworkInfo,\n  TopAsset,\n  TrendingSortBy,\n  TrendingToken,\n  TopGainersSortOption,\n  TrendingSortOption,\n  V1SuggestedOccurrenceFloorsResponse,\n  // Tokens API types\n  V1TokenSupportedNetworksResponse,\n  V2TokenSupportedNetworksResponse,\n  V3AssetResponse,\n} from './api/index.js';\n"]}

package/dist/ws/ChannelSubscriptionManager.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Shared per-channel WebSocket subscription lifecycle manager.
+ *
+ * Extracts the channel-agnostic subscription machinery that was originally part
+ * of {@link OHLCVService}: reference counting, grace-period unsubscribe,
+ * grace-period flush, unsubscribe retry with backoff + force reconnection,
+ * idempotency checks, resubscribe-on-reconnect, and optional system-notification
+ * channel registration.
+ *
+ * It is consumed by **composition** (not inheritance). Each domain service
+ * (e.g. OHLCV market data, Launchpad token details) constructs a manager,
+ * provides the channel-type namespace and a per-message callback, and keeps its
+ * own domain concerns (channel-string construction, payload parsing, published
+ * events). The manager talks to {@link BackendWebSocketService} exclusively
+ * through the messenger — no direct import of the class.
+ */
+import type { Messenger } from '@metamask/messenger';
+import type { BackendWebSocketServiceMethodActions } from './BackendWebSocketService-method-action-types.js';
+import type { WebSocketConnectionInfo, BackendWebSocketServiceConnectionStateChangedEvent, ServerNotificationMessage } from './BackendWebSocketService.js';
+/**
+ * The `BackendWebSocketService:*` actions the manager calls through its host
+ * service's messenger. A domain service must grant (at least) these to its
+ * restricted messenger, since the manager borrows that messenger and performs
+ * all WebSocket calls on the service's behalf. Services should source their own
+ * `*_ALLOWED_ACTIONS` export from this list rather than re-declaring it.
+ */
+export declare const CHANNEL_SUBSCRIPTION_MANAGER_ALLOWED_ACTIONS: readonly ['BackendWebSocketService:connect', 'BackendWebSocketService:forceReconnection', 'BackendWebSocketService:subscribe', 'BackendWebSocketService:channelHasSubscription', 'BackendWebSocketService:getSubscriptionsByChannel', 'BackendWebSocketService:addChannelCallback', 'BackendWebSocketService:removeChannelCallback'];
+/**
+ * The `BackendWebSocketService:*` events the manager subscribes to through its
+ * host service's messenger.
+ */
+export declare const CHANNEL_SUBSCRIPTION_MANAGER_ALLOWED_EVENTS: readonly ['BackendWebSocketService:connectionStateChanged'];
+/**
+ * Minimal messenger shape the manager requires: the `BackendWebSocketService:*`
+ * actions and the `connectionStateChanged` event. A host service's messenger
+ * (which has these delegated plus its own domain actions/events) satisfies this.
+ */
+export type ChannelSubscriptionManagerMessenger = Messenger<string, BackendWebSocketServiceMethodActions, BackendWebSocketServiceConnectionStateChangedEvent>;
+/** The kind of operation that failed, forwarded to `onSubscriptionError`. */
+export type ChannelSubscriptionOperation = 'subscribe' | 'unsubscribe';
+/**
+ * Configuration for a {@link ChannelSubscriptionManager}.
+ */
+export type ChannelSubscriptionManagerOptions = {
+    /** Messenger used to reach {@link BackendWebSocketService}. */
+    messenger: ChannelSubscriptionManagerMessenger;
+    /** Channel type/namespace passed to `BackendWebSocketService:subscribe`. */
+    channelType: string;
+    /** Called for each subscription notification on a managed channel. */
+    onMessage: (channel: string, notification: ServerNotificationMessage) => void;
+    /** Called when a subscribe/unsubscribe operation fails. */
+    onSubscriptionError?: (channel: string, error: string, operation: ChannelSubscriptionOperation) => void;
+    /** Optional system-notifications channel to register a callback for on `init()`. */
+    systemNotificationsChannel?: string;
+    /** Handler invoked for messages on the system-notifications channel. */
+    onSystemNotification?: (notification: ServerNotificationMessage) => void;
+    /**
+     * Called on every connection state change, after the manager performs its own
+     * resubscribe-on-CONNECTED. Lets the host run domain reactions (e.g. marking
+     * tracked chains down on DISCONNECTED).
+     */
+    onConnectionStateChange?: (connectionInfo: WebSocketConnectionInfo) => void;
+    /** Prefix used in log lines (defaults to the channel type). */
+    logPrefix?: string;
+    /** Override the grace period (primarily for tests). */
+    gracePeriodMs?: number;
+    /** Override the unsubscribe retry backoff delays (primarily for tests). */
+    unsubRetryDelaysMs?: number[];
+};
+/**
+ * Manages the lifecycle of per-channel WebSocket subscriptions on top of the
+ * shared {@link BackendWebSocketService}.
+ */
+export declare class ChannelSubscriptionManager {
+    #private;
+    constructor(options: ChannelSubscriptionManagerOptions);
+    /**
+     * Register the system-notifications channel callback, if configured.
+     */
+    init(): void;
+    /**
+     * Subscribe to a channel. If this is the first subscriber a WebSocket
+     * subscription is created; additional calls for the same channel only bump the
+     * reference count.
+     *
+     * @param channel - The fully-qualified channel name.
+     * @returns A promise that resolves once the subscription is established.
+     */
+    subscribe(channel: string): Promise<void>;
+    /**
+     * Unsubscribe from a channel. Decrements the reference count and, when it
+     * reaches zero, starts a grace-period timer before actually unsubscribing from
+     * the WebSocket to absorb rapid navigation patterns.
+     *
+     * @param channel - The fully-qualified channel name.
+     * @returns A promise that resolves once the unsubscription is processed.
+     */
+    unsubscribe(channel: string): Promise<void>;
+    /**
+     * Tear down all channel timers and, if configured, remove the
+     * system-notifications channel callback.
+     */
+    destroy(): void;
+}
+//# sourceMappingURL=ChannelSubscriptionManager.d.ts.map

package/dist/ws/ChannelSubscriptionManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ChannelSubscriptionManager.d.ts","sourceRoot":"","sources":["../../src/ws/ChannelSubscriptionManager.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAKrD,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,kDAAkD,CAAC;AAC7G,OAAO,KAAK,EACV,uBAAuB,EACvB,kDAAkD,EAClD,yBAAyB,EAC1B,MAAM,8BAA8B,CAAC;AAatC;;;;;;GAMG;AACH,eAAO,MAAM,4CAA4C,YACvD,iCAAiC,EACjC,2CAA2C,EAC3C,mCAAmC,EACnC,gDAAgD,EAChD,mDAAmD,EACnD,4CAA4C,EAC5C,+CAA+C,CACvC,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,2CAA2C,YACtD,gDAAgD,CACxC,CAAC;AAYX;;;;GAIG;AACH,MAAM,MAAM,mCAAmC,GAAG,SAAS,CACzD,MAAM,EACN,oCAAoC,EACpC,kDAAkD,CACnD,CAAC;AAEF,6EAA6E;AAC7E,MAAM,MAAM,4BAA4B,GAAG,WAAW,GAAG,aAAa,CAAC;AAEvE;;GAEG;AACH,MAAM,MAAM,iCAAiC,GAAG;IAC9C,+DAA+D;IAC/D,SAAS,EAAE,mCAAmC,CAAC;IAC/C,4EAA4E;IAC5E,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,YAAY,EAAE,yBAAyB,KAAK,IAAI,CAAC;IAC9E,2DAA2D;IAC3D,mBAAmB,CAAC,EAAE,CACpB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,4BAA4B,KACpC,IAAI,CAAC;IACV,oFAAoF;IACpF,0BAA0B,CAAC,EAAE,MAAM,CAAC;IACpC,wEAAwE;IACxE,oBAAoB,CAAC,EAAE,CAAC,YAAY,EAAE,yBAAyB,KAAK,IAAI,CAAC;IACzE;;;;OAIG;IACH,uBAAuB,CAAC,EAAE,CAAC,cAAc,EAAE,uBAAuB,KAAK,IAAI,CAAC;IAC5E,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,2EAA2E;IAC3E,kBAAkB,CAAC,EAAE,MAAM,EAAE,CAAC;CAC/B,CAAC;AAMF;;;GAGG;AACH,qBAAa,0BAA0B;;IAiBrC,YAAY,OAAO,EAAE,iCAAiC,EAgCrD;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,CAWX;IAMD;;;;;;;OAOG;IACG,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAO9C;IA2FD;;;;;;;OAOG;IACG,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAOhD;IAiPD;;;OAGG;IACH,OAAO,IAAI,IAAI,CAad;CACF"}

package/dist/ws/ChannelSubscriptionManager.js

@@ -0,0 +1,413 @@
+/**
+ * Shared per-channel WebSocket subscription lifecycle manager.
+ *
+ * Extracts the channel-agnostic subscription machinery that was originally part
+ * of {@link OHLCVService}: reference counting, grace-period unsubscribe,
+ * grace-period flush, unsubscribe retry with backoff + force reconnection,
+ * idempotency checks, resubscribe-on-reconnect, and optional system-notification
+ * channel registration.
+ *
+ * It is consumed by **composition** (not inheritance). Each domain service
+ * (e.g. OHLCV market data, Launchpad token details) constructs a manager,
+ * provides the channel-type namespace and a per-message callback, and keeps its
+ * own domain concerns (channel-string construction, payload parsing, published
+ * events). The manager talks to {@link BackendWebSocketService} exclusively
+ * through the messenger — no direct import of the class.
+ */
+import { Mutex } from 'async-mutex';
+import { handleAll, IterableBackoff, retry } from 'cockatiel';
+import { projectLogger, createModuleLogger } from '../logger.js';
+import { WebSocketState } from './BackendWebSocketService.js';
+// =============================================================================
+// Constants
+// =============================================================================
+/** Default delay before actually unsubscribing after refCount reaches 0. */
+const DEFAULT_GRACE_PERIOD_MS = 3_000;
+/** Default backoff delays between failed WebSocket unsubscribe attempts. */
+const DEFAULT_UNSUB_RETRY_DELAYS_MS = [1_000, 2_000, 4_000];
+/**
+ * The `BackendWebSocketService:*` actions the manager calls through its host
+ * service's messenger. A domain service must grant (at least) these to its
+ * restricted messenger, since the manager borrows that messenger and performs
+ * all WebSocket calls on the service's behalf. Services should source their own
+ * `*_ALLOWED_ACTIONS` export from this list rather than re-declaring it.
+ */
+export const CHANNEL_SUBSCRIPTION_MANAGER_ALLOWED_ACTIONS = [
+    'BackendWebSocketService:connect',
+    'BackendWebSocketService:forceReconnection',
+    'BackendWebSocketService:subscribe',
+    'BackendWebSocketService:channelHasSubscription',
+    'BackendWebSocketService:getSubscriptionsByChannel',
+    'BackendWebSocketService:addChannelCallback',
+    'BackendWebSocketService:removeChannelCallback',
+];
+/**
+ * The `BackendWebSocketService:*` events the manager subscribes to through its
+ * host service's messenger.
+ */
+export const CHANNEL_SUBSCRIPTION_MANAGER_ALLOWED_EVENTS = [
+    'BackendWebSocketService:connectionStateChanged',
+];
+// =============================================================================
+// Class
+// =============================================================================
+/**
+ * Manages the lifecycle of per-channel WebSocket subscriptions on top of the
+ * shared {@link BackendWebSocketService}.
+ */
+export class ChannelSubscriptionManager {
+    #messenger;
+    #options;
+    #channelType;
+    #channels = new Map();
+    #mutex = new Mutex();
+    #gracePeriodMs;
+    #log;
+    #unsubRetryPolicy;
+    constructor(options) {
+        this.#options = options;
+        this.#messenger = options.messenger;
+        this.#channelType = options.channelType;
+        this.#gracePeriodMs = options.gracePeriodMs ?? DEFAULT_GRACE_PERIOD_MS;
+        const retryDelays = options.unsubRetryDelaysMs ?? [
+            ...DEFAULT_UNSUB_RETRY_DELAYS_MS,
+        ];
+        this.#unsubRetryPolicy = retry(handleAll, {
+            // Cockatiel stops retrying once the failure index reaches `maxAttempts`,
+            // so `length` yields one initial attempt plus the delayed retries.
+            maxAttempts: retryDelays.length,
+            backoff: new IterableBackoff([...retryDelays]),
+        });
+        const prefix = options.logPrefix ?? options.channelType;
+        const moduleLog = createModuleLogger(projectLogger, 'ChannelSubscriptionManager');
+        this.#log = (message, data) => data === undefined
+            ? moduleLog(`${prefix}: ${message}`)
+            : moduleLog(`${prefix}: ${message}`, data);
+        this.#messenger.subscribe('BackendWebSocketService:connectionStateChanged', 
+        // eslint-disable-next-line @typescript-eslint/no-misused-promises
+        (connectionInfo) => this.#handleWebSocketStateChange(connectionInfo));
+    }
+    /**
+     * Register the system-notifications channel callback, if configured.
+     */
+    init() {
+        const { systemNotificationsChannel, onSystemNotification } = this.#options;
+        if (!systemNotificationsChannel || !onSystemNotification) {
+            return;
+        }
+        this.#log('Initializing — registering system-notifications callback');
+        this.#messenger.call('BackendWebSocketService:addChannelCallback', {
+            channelName: systemNotificationsChannel,
+            callback: (notification) => onSystemNotification(notification),
+        });
+    }
+    // =============================================================================
+    // Public — Subscribe / Unsubscribe
+    // =============================================================================
+    /**
+     * Subscribe to a channel. If this is the first subscriber a WebSocket
+     * subscription is created; additional calls for the same channel only bump the
+     * reference count.
+     *
+     * @param channel - The fully-qualified channel name.
+     * @returns A promise that resolves once the subscription is established.
+     */
+    async subscribe(channel) {
+        const releaseLock = await this.#mutex.acquire();
+        try {
+            await this.#subscribeInner(channel);
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    async #subscribeInner(channel) {
+        const entry = this.#channels.get(channel);
+        if (entry?.retryAbort) {
+            entry.retryAbort.abort();
+            entry.retryAbort = undefined;
+            entry.refCount = 1;
+            if (this.#messenger.call('BackendWebSocketService:channelHasSubscription', channel)) {
+                await this.#flushOtherChannels(channel);
+                this.#log('Cancelled unsubscribe retry — reusing WS subscription', {
+                    channel,
+                });
+                return;
+            }
+            // WS subscription was lost — fall through to recreate it.
+        }
+        else if (entry?.gracePeriodTimer) {
+            clearTimeout(entry.gracePeriodTimer);
+            entry.gracePeriodTimer = undefined;
+            this.#log('Cancelled grace-period unsubscribe', {
+                channel,
+            });
+            if (this.#messenger.call('BackendWebSocketService:channelHasSubscription', channel)) {
+                await this.#flushOtherChannels(channel);
+                entry.refCount += 1;
+                this.#log('WS subscription still alive, bumped refCount', {
+                    channel,
+                    refCount: entry.refCount,
+                });
+                return;
+            }
+            // WS subscription was lost (e.g. after disconnect/reconnect) — fall
+            // through to recreate it. refCount is bumped only after success below.
+        }
+        else if (entry && entry.refCount > 0) {
+            entry.refCount += 1;
+            return;
+        }
+        await this.#flushOtherChannels(channel);
+        try {
+            await this.#messenger.call('BackendWebSocketService:connect');
+            if (this.#messenger.call('BackendWebSocketService:channelHasSubscription', channel)) {
+                this.#log('Channel already has WS subscription (idempotency), skipping', {
+                    channel,
+                });
+                this.#channels.set(channel, { refCount: 1 });
+                return;
+            }
+            await this.#messenger.call('BackendWebSocketService:subscribe', {
+                channels: [channel],
+                channelType: this.#channelType,
+                callback: (notification) => {
+                    this.#options.onMessage(channel, notification);
+                },
+            });
+            this.#channels.set(channel, { refCount: 1 });
+            this.#log('Subscribe succeeded — new WS subscription created', {
+                channel,
+            });
+        }
+        catch (error) {
+            this.#log('Subscription failed', { channel, error });
+            this.#channels.delete(channel);
+            this.#options.onSubscriptionError?.(channel, String(error), 'subscribe');
+        }
+    }
+    /**
+     * Unsubscribe from a channel. Decrements the reference count and, when it
+     * reaches zero, starts a grace-period timer before actually unsubscribing from
+     * the WebSocket to absorb rapid navigation patterns.
+     *
+     * @param channel - The fully-qualified channel name.
+     * @returns A promise that resolves once the unsubscription is processed.
+     */
+    async unsubscribe(channel) {
+        const releaseLock = await this.#mutex.acquire();
+        try {
+            await this.#unsubscribeInner(channel);
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    async #unsubscribeInner(channel) {
+        const entry = this.#channels.get(channel);
+        if (!entry || entry.refCount <= 0) {
+            return;
+        }
+        entry.refCount -= 1;
+        if (entry.refCount > 0) {
+            return;
+        }
+        entry.gracePeriodTimer = setTimeout(() => {
+            entry.gracePeriodTimer = undefined;
+            this.#performUnsubscribe(channel).catch(() => {
+                // no-op: retry scheduling and force-reconnection are handled internally
+            });
+        }, this.#gracePeriodMs);
+    }
+    // =============================================================================
+    // Private — WebSocket Subscription Helpers
+    // =============================================================================
+    /**
+     * Immediately unsubscribe other channels in grace or failed-cleanup state.
+     * Called while the subscribe mutex is held before opening a new channel.
+     *
+     * @param exceptChannel - Channel being subscribed; excluded from flush.
+     */
+    async #flushOtherChannels(exceptChannel) {
+        for (const [channel, channelEntry] of this.#channels.entries()) {
+            if (channel === exceptChannel || channelEntry.refCount > 0) {
+                continue;
+            }
+            this.#clearChannelTimers(channelEntry);
+            this.#log('Flushing grace-period channel before new subscribe', {
+                flushedChannel: channel,
+                newChannel: exceptChannel,
+            });
+            const success = await this.#unsubscribeChannelOnServer(channel);
+            if (success) {
+                this.#channels.delete(channel);
+            }
+            else {
+                this.#scheduleUnsubscribeRetry(channel);
+            }
+        }
+    }
+    #clearChannelTimers(entry) {
+        if (entry.gracePeriodTimer) {
+            clearTimeout(entry.gracePeriodTimer);
+            entry.gracePeriodTimer = undefined;
+        }
+        entry.retryAbort?.abort();
+        entry.retryAbort = undefined;
+    }
+    async #unsubscribeChannelOnServer(channel) {
+        try {
+            const subscriptions = this.#messenger.call('BackendWebSocketService:getSubscriptionsByChannel', channel);
+            for (const sub of subscriptions) {
+                await sub.unsubscribe();
+            }
+            return true;
+        }
+        catch (error) {
+            this.#log('Unsubscription failed', { channel, error });
+            this.#options.onSubscriptionError?.(channel, String(error), 'unsubscribe');
+            return false;
+        }
+    }
+    #scheduleUnsubscribeRetry(channel) {
+        const entry = this.#channels.get(channel);
+        if (!entry) {
+            // The channel was removed (e.g. destroy() or reconnect cleanup) while the
+            // unsubscribe was in flight. Do not resurrect it or start a new retry loop
+            // with an AbortController that teardown can no longer cancel — that could
+            // force a reconnection on the shared WebSocket after teardown.
+            return;
+        }
+        entry.retryAbort?.abort();
+        entry.retryAbort = new AbortController();
+        const { signal } = entry.retryAbort;
+        // eslint-disable-next-line @typescript-eslint/no-floating-promises
+        this.#runUnsubRetryLoop(channel, signal);
+    }
+    async #runUnsubRetryLoop(channel, signal) {
+        try {
+            await this.#unsubRetryPolicy.execute(async () => {
+                const releaseLock = await this.#mutex.acquire();
+                try {
+                    const current = this.#channels.get(channel);
+                    if (current && current.refCount > 0) {
+                        return;
+                    }
+                    const success = await this.#unsubscribeChannelOnServer(channel);
+                    if (!success) {
+                        throw new Error('unsubscribe failed');
+                    }
+                    this.#channels.delete(channel);
+                    this.#log('WS unsubscribe completed', { channel });
+                }
+                finally {
+                    releaseLock();
+                }
+            }, signal);
+        }
+        catch {
+            if (signal.aborted) {
+                return;
+            }
+            this.#log('Unsubscribe retries exhausted — forcing reconnection', {
+                channel,
+            });
+            this.#channels.delete(channel);
+            // Last resort: reconnects the shared BackendWebSocketService instance
+            // (other consumers share this connection). They resubscribe on CONNECTED;
+            // this manager only resubscribes channels with refCount > 0.
+            await this.#messenger
+                .call('BackendWebSocketService:forceReconnection')
+                .catch(() => {
+                // no-op
+            });
+        }
+    }
+    async #performUnsubscribe(channel) {
+        const releaseLock = await this.#mutex.acquire();
+        try {
+            const entry = this.#channels.get(channel);
+            if (entry && entry.refCount > 0) {
+                this.#log('Skipping unsubscribe — new subscriber arrived while queued', { channel, refCount: entry.refCount });
+                return;
+            }
+            this.#log('Grace period expired — performing actual WS unsubscribe', {
+                channel,
+            });
+            this.#clearChannelTimers(this.#channels.get(channel) ?? { refCount: 0 });
+        }
+        finally {
+            releaseLock();
+        }
+        this.#scheduleUnsubscribeRetry(channel);
+    }
+    /**
+     * Resubscribe all channels that were active before a disconnect.
+     * Called when WebSocket transitions to CONNECTED.
+     */
+    async #resubscribeActiveChannels() {
+        const releaseLock = await this.#mutex.acquire();
+        try {
+            const channelCount = this.#channels.size;
+            this.#log('Resubscribing active channels after reconnect', {
+                count: channelCount,
+            });
+            for (const [channel, entry] of [...this.#channels.entries()]) {
+                if (entry.refCount === 0) {
+                    this.#clearChannelTimers(entry);
+                    this.#channels.delete(channel);
+                    continue;
+                }
+                try {
+                    if (this.#messenger.call('BackendWebSocketService:channelHasSubscription', channel)) {
+                        this.#log('Channel already subscribed on server, skipping resubscribe', {
+                            channel,
+                        });
+                        continue;
+                    }
+                    await this.#messenger.call('BackendWebSocketService:subscribe', {
+                        channels: [channel],
+                        channelType: this.#channelType,
+                        callback: (notification) => {
+                            this.#options.onMessage(channel, notification);
+                        },
+                    });
+                    this.#log('Resubscription succeeded', { channel });
+                }
+                catch (error) {
+                    this.#log('Resubscription failed for channel', {
+                        channel,
+                        error,
+                    });
+                }
+            }
+        }
+        finally {
+            releaseLock();
+        }
+    }
+    async #handleWebSocketStateChange(connectionInfo) {
+        if (connectionInfo.state === WebSocketState.CONNECTED) {
+            await this.#resubscribeActiveChannels();
+        }
+        this.#options.onConnectionStateChange?.(connectionInfo);
+    }
+    // =============================================================================
+    // Public — Cleanup
+    // =============================================================================
+    /**
+     * Tear down all channel timers and, if configured, remove the
+     * system-notifications channel callback.
+     */
+    destroy() {
+        for (const entry of this.#channels.values()) {
+            this.#clearChannelTimers(entry);
+        }
+        this.#channels.clear();
+        const { systemNotificationsChannel } = this.#options;
+        if (systemNotificationsChannel) {
+            this.#messenger.call('BackendWebSocketService:removeChannelCallback', systemNotificationsChannel);
+        }
+    }
+}
+//# sourceMappingURL=ChannelSubscriptionManager.js.map