@metamask-previews/core-backend 5.0.0-preview-fa81dffb → 5.0.0-preview-ab102d86

package/CHANGELOG.md

@@ -7,6 +7,15 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add `ApiPlatformClient` for unified access to MetaMask backend APIs with TanStack Query caching ([#7658](https://github.com/MetaMask/core/pull/7658))
+  - Automatic request deduplication and intelligent caching
+  - Automatic retries with exponential backoff for transient failures
+  - Support for Accounts API, Price API, Token API, and Tokens API endpoints
+  - Export helper functions `shouldRetry` and `calculateRetryDelay` for custom retry logic
+  - Export API types for external consumers
+
 ### Changed
 
 - Upgrade `@metamask/utils` from `^11.8.1` to `^11.9.0` ([#7511](https://github.com/MetaMask/core/pull/7511))

package/README.md

@@ -19,6 +19,17 @@ Core backend services for MetaMask, serving as the data layer between Backend se
   - [WebSocket Connection Management](#websocket-connection-management)
     - [Connection Requirements](#connection-requirements)
     - [Connection Behavior](#connection-behavior)
+  - [HTTP API](#http-api)
+    - [Overview](#overview)
+    - [Features](#features)
+    - [Quick Start](#quick-start-1)
+    - [API Clients](#api-clients)
+      - [AccountsApiClient](#accountsapiclient)
+      - [PricesApiClient](#pricesapiclient)
+      - [TokenApiClient](#tokenapiclient)
+      - [TokensApiClient](#tokensapiclient)
+    - [Configuration](#configuration)
+    - [Cache Management](#cache-management)
   - [API Reference](#api-reference)
     - [BackendWebSocketService](#backendwebsocketservice)
       - [Constructor Options](#constructor-options)
@@ -44,6 +55,8 @@ npm install @metamask/core-backend
 
 ### Basic Usage
 
+**WebSocket for Real-time Updates:**
+
 ```typescript
 import {
   BackendWebSocketService,
@@ -82,6 +95,28 @@ messenger.subscribe(
 );
 ```
 
+**HTTP API for REST Requests:**
+
+```typescript
+import { ApiPlatformClient } from '@metamask/core-backend';
+
+// Create API client
+const apiClient = new ApiPlatformClient({
+  clientProduct: 'metamask-extension',
+  getBearerToken: async () => authController.getBearerToken(),
+});
+
+// Fetch data with automatic caching and deduplication
+const balances = await apiClient.accounts.fetchV5MultiAccountBalances([
+  'eip155:1:0x742d35cc6634c0532925a3b8d40c4e0e2c6e4e6',
+]);
+
+const prices = await apiClient.prices.fetchV3SpotPrices([
+  'eip155:1/slip44:60', // ETH
+  'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48', // USDC
+]);
+```
+
 ### Integration with Controllers
 
 ```typescript
@@ -147,7 +182,7 @@ graph TD
 
             subgraph "Transport Layer"
                 WSS[WebSocketService<br/>• Connection management<br/>• Automatic reconnection<br/>• Message routing<br/>• Subscription management]
-                HTTP[HTTP Service<br/>• REST API calls<br/>• Request/response handling<br/>• Error handling<br/>future]
+                HTTP[HTTP API Clients<br/>• REST API calls<br/>• Automatic caching<br/>• Request deduplication<br/>• Retry with backoff]
             end
         end
     end
@@ -344,6 +379,222 @@ The WebSocket connects when **ALL 3 conditions are true**:
 - ✅ **Unexpected disconnects** (network issues, server restart) → Auto-reconnect
 - ❌ **Manual disconnects** (app backgrounds, wallet locks, user signs out) → Stay disconnected
 
+## HTTP API
+
+### Overview
+
+The HTTP API provides type-safe clients for accessing MetaMask backend REST APIs. It uses `@tanstack/query-core` for intelligent caching, request deduplication, and automatic retries.
+
+**Available APIs:**
+
+| API          | Base URL                      | Purpose                                        |
+| ------------ | ----------------------------- | ---------------------------------------------- |
+| **Accounts** | `accounts.api.cx.metamask.io` | Balances, transactions, NFTs, token discovery  |
+| **Prices**   | `price.api.cx.metamask.io`    | Spot prices, exchange rates, historical prices |
+| **Token**    | `token.api.cx.metamask.io`    | Token metadata, trending, top gainers          |
+| **Tokens**   | `tokens.api.cx.metamask.io`   | Bulk asset operations, supported networks      |
+
+### Features
+
+- ✅ **Automatic request deduplication** - Identical concurrent requests share a single network call
+- ✅ **Intelligent caching** - Configurable stale times per data type (prices: 30s, balances: 1min, networks: 30min)
+- ✅ **Automatic retries** - Exponential backoff with jitter, skips 4xx errors (except 429, 408)
+- ✅ **Type safety** - Full TypeScript support with response types
+- ✅ **Bearer token caching** - Auth tokens cached for 5 minutes
+- ✅ **Unified client** - Single entry point or individual API clients
+
+### Quick Start
+
+```typescript
+import {
+  ApiPlatformClient,
+  createApiPlatformClient,
+} from '@metamask/core-backend';
+
+// Create unified client
+const client = new ApiPlatformClient({
+  clientProduct: 'metamask-extension',
+  clientVersion: '12.0.0',
+  getBearerToken: async () => authController.getBearerToken(),
+});
+
+// Access API methods through sub-clients
+const networks = await client.accounts.fetchV2SupportedNetworks();
+const balances = await client.accounts.fetchV5MultiAccountBalances([
+  'eip155:1:0x742d35cc6634c0532925a3b8d40c4e0e2c6e4e6',
+]);
+const prices = await client.prices.fetchV3SpotPrices([
+  'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+]);
+const tokenList = await client.token.fetchTokenList(1);
+const assets = await client.tokens.fetchV3Assets([
+  'eip155:1/erc20:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48',
+]);
+```
+
+Or use individual clients:
+
+```typescript
+import { AccountsApiClient, PricesApiClient } from '@metamask/core-backend';
+
+const accountsClient = new AccountsApiClient({
+  clientProduct: 'metamask-extension',
+});
+
+const pricesClient = new PricesApiClient({
+  clientProduct: 'metamask-extension',
+  getBearerToken: async () => token,
+});
+```
+
+### API Clients
+
+#### AccountsApiClient
+
+Handles account-related operations including balances, transactions, NFTs, and token discovery.
+
+| Method                                                  | Description                                |
+| ------------------------------------------------------- | ------------------------------------------ |
+| `fetchV1SupportedNetworks()`                            | Get supported networks (v1)                |
+| `fetchV2SupportedNetworks()`                            | Get supported networks (v2)                |
+| `fetchV2ActiveNetworks(accountIds, options?)`           | Get active networks by CAIP-10 account IDs |
+| `fetchV2Balances(address, options?)`                    | Get balances for single address            |
+| `fetchV2BalancesWithOptions(address, options?)`         | Get balances with filters                  |
+| `fetchV4MultiAccountBalances(addresses, options?)`      | Get balances for multiple addresses        |
+| `fetchV5MultiAccountBalances(accountIds, options?)`     | Get balances using CAIP-10 IDs             |
+| `fetchV1TransactionByHash(chainId, txHash, options?)`   | Get transaction by hash                    |
+| `fetchV1AccountTransactions(address, options?)`         | Get account transactions                   |
+| `fetchV4MultiAccountTransactions(accountIds, options?)` | Get multi-account transactions             |
+| `fetchV1AccountRelationship(chainId, from, to)`         | Get address relationship                   |
+| `fetchV2AccountNfts(address, options?)`                 | Get account NFTs                           |
+| `fetchV2AccountTokens(address, options?)`               | Get detected ERC20 tokens                  |
+| `invalidateBalances()`                                  | Invalidate all balance cache               |
+| `invalidateAccounts()`                                  | Invalidate all account cache               |
+
+#### PricesApiClient
+
+Handles price-related operations including spot prices, exchange rates, and historical data.
+
+| Method                                                                  | Description                                      |
+| ----------------------------------------------------------------------- | ------------------------------------------------ |
+| `fetchPriceV1SupportedNetworks()`                                       | Get price-supported networks (v1)                |
+| `fetchPriceV2SupportedNetworks()`                                       | Get price-supported networks in CAIP format (v2) |
+| `fetchV1ExchangeRates(baseCurrency)`                                    | Get exchange rates for base currency             |
+| `fetchV1FiatExchangeRates()`                                            | Get fiat exchange rates                          |
+| `fetchV1CryptoExchangeRates()`                                          | Get crypto exchange rates                        |
+| `fetchV1SpotPricesByCoinIds(coinIds)`                                   | Get spot prices by CoinGecko IDs                 |
+| `fetchV1SpotPriceByCoinId(coinId, currency?)`                           | Get single coin spot price                       |
+| `fetchV1TokenPrices(chainId, addresses, options?)`                      | Get token prices on chain                        |
+| `fetchV1TokenPrice(chainId, address, currency?)`                        | Get single token price                           |
+| `fetchV2SpotPrices(chainId, addresses, options?)`                       | Get spot prices with market data                 |
+| `fetchV3SpotPrices(assetIds, options?)`                                 | Get spot prices by CAIP-19 asset IDs             |
+| `fetchV1HistoricalPricesByCoinId(coinId, options?)`                     | Get historical prices by CoinGecko ID            |
+| `fetchV1HistoricalPricesByTokenAddresses(chainId, addresses, options?)` | Get historical prices for tokens                 |
+| `fetchV1HistoricalPrices(chainId, address, options?)`                   | Get historical prices for single token           |
+| `fetchV3HistoricalPrices(chainId, assetType, options?)`                 | Get historical prices by CAIP-19                 |
+| `fetchV1HistoricalPriceGraphByCoinId(coinId, options?)`                 | Get price graph by CoinGecko ID                  |
+| `fetchV1HistoricalPriceGraphByTokenAddress(chainId, address, options?)` | Get price graph by token address                 |
+| `invalidatePrices()`                                                    | Invalidate all price cache                       |
+
+#### TokenApiClient
+
+Handles token metadata, lists, and trending/popular token discovery.
+
+| Method                                             | Description                     |
+| -------------------------------------------------- | ------------------------------- |
+| `fetchNetworks()`                                  | Get all networks                |
+| `fetchNetworkByChainId(chainId)`                   | Get network by chain ID         |
+| `fetchTokenList(chainId, options?)`                | Get token list for chain        |
+| `fetchV1TokenMetadata(chainId, address, options?)` | Get token metadata              |
+| `fetchTokenDescription(chainId, address)`          | Get token description           |
+| `fetchV3TrendingTokens(chainIds, options?)`        | Get trending tokens             |
+| `fetchV3TopGainers(chainIds, options?)`            | Get top gainers/losers          |
+| `fetchV3PopularTokens(chainIds, options?)`         | Get popular tokens              |
+| `fetchTopAssets(chainId)`                          | Get top assets for chain        |
+| `fetchV1SuggestedOccurrenceFloors()`               | Get suggested occurrence floors |
+
+#### TokensApiClient
+
+Handles bulk token operations and supported network queries.
+
+| Method                            | Description                                                 |
+| --------------------------------- | ----------------------------------------------------------- |
+| `fetchTokenV1SupportedNetworks()` | Get token-supported networks (v1)                           |
+| `fetchTokenV2SupportedNetworks()` | Get token-supported networks with full/partial support (v2) |
+| `fetchV3Assets(assetIds)`         | Fetch assets by CAIP-19 IDs                                 |
+| `invalidateTokens()`              | Invalidate all token cache                                  |
+
+### Configuration
+
+```typescript
+type ApiPlatformClientOptions = {
+  /** Client product identifier (e.g., 'metamask-extension', 'metamask-mobile') */
+  clientProduct: string;
+  /** Optional client version (default: '1.0.0') */
+  clientVersion?: string;
+  /** Function to get bearer token for authenticated requests */
+  getBearerToken?: () => Promise<string | undefined>;
+  /** Optional custom QueryClient instance for shared caching */
+  queryClient?: QueryClient;
+};
+```
+
+**Default Stale Times:**
+
+| Data Type          | Stale Time |
+| ------------------ | ---------- |
+| Prices             | 30 seconds |
+| Balances           | 1 minute   |
+| Transactions       | 30 seconds |
+| Networks           | 10 minutes |
+| Supported Networks | 30 minutes |
+| Token Metadata     | 5 minutes  |
+| Token List         | 10 minutes |
+| Exchange Rates     | 5 minutes  |
+| Trending           | 2 minutes  |
+| Auth Token         | 5 minutes  |
+
+**Override Stale Time:**
+
+```typescript
+// Use custom stale time for specific request
+const balances = await client.accounts.fetchV5MultiAccountBalances(
+  accountIds,
+  { networks: ['eip155:1'] },
+  { staleTime: 10000 }, // 10 seconds
+);
+```
+
+### Cache Management
+
+```typescript
+// Invalidate all caches
+await client.invalidateAll();
+
+// Invalidate auth token (on logout)
+await client.invalidateAuthToken();
+
+// Domain-specific invalidation
+await client.accounts.invalidateBalances();
+await client.prices.invalidatePrices();
+await client.tokens.invalidateTokens();
+
+// Clear all cached data
+client.clear();
+
+// Check if query is fetching
+const isFetching = client.isFetching(['accounts', 'balances']);
+
+// Access cached data directly
+const cached = client.getCachedData(['accounts', 'balances', 'v5', { ... }]);
+
+// Set cached data
+client.setCachedData(queryKey, data);
+
+// Access underlying QueryClient for advanced usage
+const queryClient = client.queryClient;
+```
+
 ## API Reference
 
 ### BackendWebSocketService

package/dist/api/ApiPlatformClient.cjs

@@ -0,0 +1,173 @@
+"use strict";
+/**
+ * ApiPlatformClient - MetaMask API Platform Client
+ *
+ * A comprehensive API client that uses @tanstack/query-core directly for:
+ * - Automatic request deduplication
+ * - Intelligent caching
+ * - Automatic retries with exponential backoff
+ *
+ * Provides unified access to all MetaMask backend APIs:
+ * - Accounts API (accounts.api.cx.metamask.io)
+ * - Price API (price.api.cx.metamask.io)
+ * - Token API (token.api.cx.metamask.io)
+ * - Tokens API (tokens.api.cx.metamask.io)
+ *
+ * @example
+ * ```typescript
+ * const client = new ApiPlatformClient({
+ *   clientProduct: 'metamask-extension',
+ *   getBearerToken: async () => token,
+ * });
+ *
+ * // Access API methods through sub-clients
+ * const networks = await client.accounts.fetchV2SupportedNetworks();
+ * const balances = await client.accounts.fetchV5MultiAccountBalances(accountIds);
+ * const prices = await client.prices.fetchV3SpotPrices(assetIds);
+ * const tokenList = await client.token.fetchTokenList(1);
+ * const assets = await client.tokens.fetchV3Assets(assetIds);
+ *
+ * // Cache management
+ * await client.invalidateAll();           // Invalidate all caches
+ * await client.invalidateAuthToken();     // Invalidate auth token
+ * await client.accounts.invalidateBalances(); // Domain-specific via sub-client
+ * await client.prices.invalidatePrices();     // Domain-specific via sub-client
+ * ```
+ */
+var __classPrivateFieldSet = (this && this.__classPrivateFieldSet) || function (receiver, state, value, kind, f) {
+    if (kind === "m") throw new TypeError("Private method is not writable");
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a setter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot write private member to an object whose class did not declare it");
+    return (kind === "a" ? f.call(receiver, value) : f ? f.value = value : state.set(receiver, value)), value;
+};
+var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (receiver, state, kind, f) {
+    if (kind === "a" && !f) throw new TypeError("Private accessor was defined without a getter");
+    if (typeof state === "function" ? receiver !== state || !f : !state.has(receiver)) throw new TypeError("Cannot read private member from an object whose class did not declare it");
+    return kind === "m" ? f : kind === "a" ? f.call(receiver) : f ? f.value : state.get(receiver);
+};
+var _ApiPlatformClient_sharedQueryClient;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createApiPlatformClient = exports.ApiPlatformClient = void 0;
+const query_core_1 = require("@tanstack/query-core");
+// Import API clients from subfolders
+const accounts_1 = require("./accounts/index.cjs");
+const prices_1 = require("./prices/index.cjs");
+const shared_types_1 = require("./shared-types.cjs");
+const token_1 = require("./token/index.cjs");
+const tokens_1 = require("./tokens/index.cjs");
+// ============================================================================
+// UNIFIED API CLIENT
+// ============================================================================
+/**
+ * MetaMask API Platform Client with TanStack Query caching.
+ * Provides cached access to all MetaMask backend APIs through a unified interface.
+ *
+ * Access API methods through the sub-clients:
+ * - `client.accounts` - Accounts API (balances, transactions, NFTs, etc.)
+ * - `client.prices` - Prices API (spot prices, exchange rates, historical prices)
+ * - `client.token` - Token API (token metadata, trending, top gainers)
+ * - `client.tokens` - Tokens API (bulk asset operations, supported networks)
+ */
+class ApiPlatformClient {
+    constructor(options) {
+        /**
+         * Shared QueryClient instance used by all sub-clients.
+         */
+        _ApiPlatformClient_sharedQueryClient.set(this, void 0);
+        // Create or use provided QueryClient - shared by all sub-clients
+        __classPrivateFieldSet(this, _ApiPlatformClient_sharedQueryClient, options.queryClient ??
+            new query_core_1.QueryClient({
+                defaultOptions: {
+                    queries: {
+                        staleTime: shared_types_1.STALE_TIMES.DEFAULT,
+                        gcTime: shared_types_1.GC_TIMES.DEFAULT,
+                        retry: shared_types_1.shouldRetry,
+                        retryDelay: shared_types_1.calculateRetryDelay,
+                        refetchOnWindowFocus: false,
+                        networkMode: 'always',
+                    },
+                },
+            }), "f");
+        // Pass the shared QueryClient to all sub-clients
+        const sharedOptions = {
+            ...options,
+            queryClient: __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f"),
+        };
+        this.accounts = new accounts_1.AccountsApiClient(sharedOptions);
+        this.prices = new prices_1.PricesApiClient(sharedOptions);
+        this.token = new token_1.TokenApiClient(sharedOptions);
+        this.tokens = new tokens_1.TokensApiClient(sharedOptions);
+    }
+    // ==========================================================================
+    // CACHE MANAGEMENT (operates on shared QueryClient)
+    // ==========================================================================
+    /**
+     * Get the underlying QueryClient (for advanced usage).
+     *
+     * @returns The underlying QueryClient instance.
+     */
+    get queryClient() {
+        return __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f");
+    }
+    /**
+     * Get cached data for a query key.
+     *
+     * @param queryKey - The query key to look up.
+     * @returns The cached data or undefined.
+     */
+    getCachedData(queryKey) {
+        return __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").getQueryData(queryKey);
+    }
+    /**
+     * Set cached data for a query key.
+     *
+     * @param queryKey - The query key to set data for.
+     * @param data - The data to cache.
+     */
+    setCachedData(queryKey, data) {
+        __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").setQueryData(queryKey, data);
+    }
+    /**
+     * Check if a query is currently fetching.
+     *
+     * @param queryKey - The query key to check.
+     * @returns True if the query is currently fetching.
+     */
+    isFetching(queryKey) {
+        return __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").isFetching({ queryKey }) > 0;
+    }
+    /**
+     * Clear all cached data across all sub-clients.
+     */
+    clear() {
+        __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").clear();
+    }
+    /**
+     * Invalidate all queries across all sub-clients.
+     */
+    async invalidateAll() {
+        await __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").invalidateQueries();
+    }
+    /**
+     * Invalidate the cached auth token.
+     * Call this when the user logs out or the token expires.
+     */
+    async invalidateAuthToken() {
+        await __classPrivateFieldGet(this, _ApiPlatformClient_sharedQueryClient, "f").invalidateQueries({
+            queryKey: shared_types_1.authQueryKeys.bearerToken(),
+        });
+    }
+}
+exports.ApiPlatformClient = ApiPlatformClient;
+_ApiPlatformClient_sharedQueryClient = new WeakMap();
+/**
+ * Factory function to create an ApiPlatformClient.
+ *
+ * @param options - Configuration options for the client.
+ * @returns A new ApiPlatformClient instance.
+ */
+function createApiPlatformClient(options) {
+    return new ApiPlatformClient(options);
+}
+exports.createApiPlatformClient = createApiPlatformClient;
+//# sourceMappingURL=ApiPlatformClient.cjs.map

package/dist/api/ApiPlatformClient.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPlatformClient.cjs","sourceRoot":"","sources":["../../src/api/ApiPlatformClient.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;;;;;;;;;;;;;;;AAEH,qDAAmD;AAGnD,qCAAqC;AACrC,mDAA+C;AAC/C,+CAA2C;AAC3C,qDAMwB;AAExB,6CAAyC;AACzC,+CAA2C;AAE3C,+EAA+E;AAC/E,qBAAqB;AACrB,+EAA+E;AAE/E;;;;;;;;;GASG;AACH,MAAa,iBAAiB;IA8B5B,YAAY,OAAiC;QAL7C;;WAEG;QACM,uDAAgC;QAGvC,iEAAiE;QACjE,uBAAA,IAAI,wCACF,OAAO,CAAC,WAAW;YACnB,IAAI,wBAAW,CAAC;gBACd,cAAc,EAAE;oBACd,OAAO,EAAE;wBACP,SAAS,EAAE,0BAAW,CAAC,OAAO;wBAC9B,MAAM,EAAE,uBAAQ,CAAC,OAAO;wBACxB,KAAK,EAAE,0BAAW;wBAClB,UAAU,EAAE,kCAAmB;wBAC/B,oBAAoB,EAAE,KAAK;wBAC3B,WAAW,EAAE,QAAQ;qBACtB;iBACF;aACF,CAAC,MAAA,CAAC;QAEL,iDAAiD;QACjD,MAAM,aAAa,GAA6B;YAC9C,GAAG,OAAO;YACV,WAAW,EAAE,uBAAA,IAAI,4CAAmB;SACrC,CAAC;QAEF,IAAI,CAAC,QAAQ,GAAG,IAAI,4BAAiB,CAAC,aAAa,CAAC,CAAC;QACrD,IAAI,CAAC,MAAM,GAAG,IAAI,wBAAe,CAAC,aAAa,CAAC,CAAC;QACjD,IAAI,CAAC,KAAK,GAAG,IAAI,sBAAc,CAAC,aAAa,CAAC,CAAC;QAC/C,IAAI,CAAC,MAAM,GAAG,IAAI,wBAAe,CAAC,aAAa,CAAC,CAAC;IACnD,CAAC;IAED,6EAA6E;IAC7E,oDAAoD;IACpD,6EAA6E;IAE7E;;;;OAIG;IACH,IAAI,WAAW;QACb,OAAO,uBAAA,IAAI,4CAAmB,CAAC;IACjC,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAa,QAAkB;QAC1C,OAAO,uBAAA,IAAI,4CAAmB,CAAC,YAAY,CAAa,QAAQ,CAAC,CAAC;IACpE,CAAC;IAED;;;;;OAKG;IACH,aAAa,CAAa,QAAkB,EAAE,IAAgB;QAC5D,uBAAA,IAAI,4CAAmB,CAAC,YAAY,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IACvD,CAAC;IAED;;;;;OAKG;IACH,UAAU,CAAC,QAAkB;QAC3B,OAAO,uBAAA,IAAI,4CAAmB,CAAC,UAAU,CAAC,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,CAAC;IAC9D,CAAC;IAED;;OAEG;IACH,KAAK;QACH,uBAAA,IAAI,4CAAmB,CAAC,KAAK,EAAE,CAAC;IAClC,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,aAAa;QACjB,MAAM,uBAAA,IAAI,4CAAmB,CAAC,iBAAiB,EAAE,CAAC;IACpD,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,mBAAmB;QACvB,MAAM,uBAAA,IAAI,4CAAmB,CAAC,iBAAiB,CAAC;YAC9C,QAAQ,EAAE,4BAAa,CAAC,WAAW,EAAE;SACtC,CAAC,CAAC;IACL,CAAC;CACF;AA7HD,8CA6HC;;AAED;;;;;GAKG;AACH,SAAgB,uBAAuB,CACrC,OAAiC;IAEjC,OAAO,IAAI,iBAAiB,CAAC,OAAO,CAAC,CAAC;AACxC,CAAC;AAJD,0DAIC","sourcesContent":["/**\n * ApiPlatformClient - MetaMask API Platform Client\n *\n * A comprehensive API client that uses @tanstack/query-core directly for:\n * - Automatic request deduplication\n * - Intelligent caching\n * - Automatic retries with exponential backoff\n *\n * Provides unified access to all MetaMask backend APIs:\n * - Accounts API (accounts.api.cx.metamask.io)\n * - Price API (price.api.cx.metamask.io)\n * - Token API (token.api.cx.metamask.io)\n * - Tokens API (tokens.api.cx.metamask.io)\n *\n * @example\n * ```typescript\n * const client = new ApiPlatformClient({\n *   clientProduct: 'metamask-extension',\n *   getBearerToken: async () => token,\n * });\n *\n * // Access API methods through sub-clients\n * const networks = await client.accounts.fetchV2SupportedNetworks();\n * const balances = await client.accounts.fetchV5MultiAccountBalances(accountIds);\n * const prices = await client.prices.fetchV3SpotPrices(assetIds);\n * const tokenList = await client.token.fetchTokenList(1);\n * const assets = await client.tokens.fetchV3Assets(assetIds);\n *\n * // Cache management\n * await client.invalidateAll();           // Invalidate all caches\n * await client.invalidateAuthToken();     // Invalidate auth token\n * await client.accounts.invalidateBalances(); // Domain-specific via sub-client\n * await client.prices.invalidatePrices();     // Domain-specific via sub-client\n * ```\n */\n\nimport { QueryClient } from '@tanstack/query-core';\nimport type { QueryKey } from '@tanstack/query-core';\n\n// Import API clients from subfolders\nimport { AccountsApiClient } from './accounts';\nimport { PricesApiClient } from './prices';\nimport {\n  STALE_TIMES,\n  GC_TIMES,\n  authQueryKeys,\n  shouldRetry,\n  calculateRetryDelay,\n} from './shared-types';\nimport type { ApiPlatformClientOptions } from './shared-types';\nimport { TokenApiClient } from './token';\nimport { TokensApiClient } from './tokens';\n\n// ============================================================================\n// UNIFIED API CLIENT\n// ============================================================================\n\n/**\n * MetaMask API Platform Client with TanStack Query caching.\n * Provides cached access to all MetaMask backend APIs through a unified interface.\n *\n * Access API methods through the sub-clients:\n * - `client.accounts` - Accounts API (balances, transactions, NFTs, etc.)\n * - `client.prices` - Prices API (spot prices, exchange rates, historical prices)\n * - `client.token` - Token API (token metadata, trending, top gainers)\n * - `client.tokens` - Tokens API (bulk asset operations, supported networks)\n */\nexport class ApiPlatformClient {\n  /**\n   * Accounts API client.\n   * Provides methods for balances, transactions, relationships, NFTs, and token discovery.\n   */\n  readonly accounts: AccountsApiClient;\n\n  /**\n   * Prices API client.\n   * Provides methods for spot prices, exchange rates, and historical prices.\n   */\n  readonly prices: PricesApiClient;\n\n  /**\n   * Token API client.\n   * Provides methods for token metadata, networks, trending tokens, and top assets.\n   */\n  readonly token: TokenApiClient;\n\n  /**\n   * Tokens API client.\n   * Provides methods for bulk asset operations and supported networks.\n   */\n  readonly tokens: TokensApiClient;\n\n  /**\n   * Shared QueryClient instance used by all sub-clients.\n   */\n  readonly #sharedQueryClient: QueryClient;\n\n  constructor(options: ApiPlatformClientOptions) {\n    // Create or use provided QueryClient - shared by all sub-clients\n    this.#sharedQueryClient =\n      options.queryClient ??\n      new QueryClient({\n        defaultOptions: {\n          queries: {\n            staleTime: STALE_TIMES.DEFAULT,\n            gcTime: GC_TIMES.DEFAULT,\n            retry: shouldRetry,\n            retryDelay: calculateRetryDelay,\n            refetchOnWindowFocus: false,\n            networkMode: 'always',\n          },\n        },\n      });\n\n    // Pass the shared QueryClient to all sub-clients\n    const sharedOptions: ApiPlatformClientOptions = {\n      ...options,\n      queryClient: this.#sharedQueryClient,\n    };\n\n    this.accounts = new AccountsApiClient(sharedOptions);\n    this.prices = new PricesApiClient(sharedOptions);\n    this.token = new TokenApiClient(sharedOptions);\n    this.tokens = new TokensApiClient(sharedOptions);\n  }\n\n  // ==========================================================================\n  // CACHE MANAGEMENT (operates on shared QueryClient)\n  // ==========================================================================\n\n  /**\n   * Get the underlying QueryClient (for advanced usage).\n   *\n   * @returns The underlying QueryClient instance.\n   */\n  get queryClient(): QueryClient {\n    return this.#sharedQueryClient;\n  }\n\n  /**\n   * Get cached data for a query key.\n   *\n   * @param queryKey - The query key to look up.\n   * @returns The cached data or undefined.\n   */\n  getCachedData<CachedData>(queryKey: QueryKey): CachedData | undefined {\n    return this.#sharedQueryClient.getQueryData<CachedData>(queryKey);\n  }\n\n  /**\n   * Set cached data for a query key.\n   *\n   * @param queryKey - The query key to set data for.\n   * @param data - The data to cache.\n   */\n  setCachedData<CachedData>(queryKey: QueryKey, data: CachedData): void {\n    this.#sharedQueryClient.setQueryData(queryKey, data);\n  }\n\n  /**\n   * Check if a query is currently fetching.\n   *\n   * @param queryKey - The query key to check.\n   * @returns True if the query is currently fetching.\n   */\n  isFetching(queryKey: QueryKey): boolean {\n    return this.#sharedQueryClient.isFetching({ queryKey }) > 0;\n  }\n\n  /**\n   * Clear all cached data across all sub-clients.\n   */\n  clear(): void {\n    this.#sharedQueryClient.clear();\n  }\n\n  /**\n   * Invalidate all queries across all sub-clients.\n   */\n  async invalidateAll(): Promise<void> {\n    await this.#sharedQueryClient.invalidateQueries();\n  }\n\n  /**\n   * Invalidate the cached auth token.\n   * Call this when the user logs out or the token expires.\n   */\n  async invalidateAuthToken(): Promise<void> {\n    await this.#sharedQueryClient.invalidateQueries({\n      queryKey: authQueryKeys.bearerToken(),\n    });\n  }\n}\n\n/**\n * Factory function to create an ApiPlatformClient.\n *\n * @param options - Configuration options for the client.\n * @returns A new ApiPlatformClient instance.\n */\nexport function createApiPlatformClient(\n  options: ApiPlatformClientOptions,\n): ApiPlatformClient {\n  return new ApiPlatformClient(options);\n}\n"]}

package/dist/api/ApiPlatformClient.d.cts

@@ -0,0 +1,124 @@
+/**
+ * ApiPlatformClient - MetaMask API Platform Client
+ *
+ * A comprehensive API client that uses @tanstack/query-core directly for:
+ * - Automatic request deduplication
+ * - Intelligent caching
+ * - Automatic retries with exponential backoff
+ *
+ * Provides unified access to all MetaMask backend APIs:
+ * - Accounts API (accounts.api.cx.metamask.io)
+ * - Price API (price.api.cx.metamask.io)
+ * - Token API (token.api.cx.metamask.io)
+ * - Tokens API (tokens.api.cx.metamask.io)
+ *
+ * @example
+ * ```typescript
+ * const client = new ApiPlatformClient({
+ *   clientProduct: 'metamask-extension',
+ *   getBearerToken: async () => token,
+ * });
+ *
+ * // Access API methods through sub-clients
+ * const networks = await client.accounts.fetchV2SupportedNetworks();
+ * const balances = await client.accounts.fetchV5MultiAccountBalances(accountIds);
+ * const prices = await client.prices.fetchV3SpotPrices(assetIds);
+ * const tokenList = await client.token.fetchTokenList(1);
+ * const assets = await client.tokens.fetchV3Assets(assetIds);
+ *
+ * // Cache management
+ * await client.invalidateAll();           // Invalidate all caches
+ * await client.invalidateAuthToken();     // Invalidate auth token
+ * await client.accounts.invalidateBalances(); // Domain-specific via sub-client
+ * await client.prices.invalidatePrices();     // Domain-specific via sub-client
+ * ```
+ */
+import { QueryClient } from "@tanstack/query-core";
+import type { QueryKey } from "@tanstack/query-core";
+import { AccountsApiClient } from "./accounts/index.cjs";
+import { PricesApiClient } from "./prices/index.cjs";
+import type { ApiPlatformClientOptions } from "./shared-types.cjs";
+import { TokenApiClient } from "./token/index.cjs";
+import { TokensApiClient } from "./tokens/index.cjs";
+/**
+ * MetaMask API Platform Client with TanStack Query caching.
+ * Provides cached access to all MetaMask backend APIs through a unified interface.
+ *
+ * Access API methods through the sub-clients:
+ * - `client.accounts` - Accounts API (balances, transactions, NFTs, etc.)
+ * - `client.prices` - Prices API (spot prices, exchange rates, historical prices)
+ * - `client.token` - Token API (token metadata, trending, top gainers)
+ * - `client.tokens` - Tokens API (bulk asset operations, supported networks)
+ */
+export declare class ApiPlatformClient {
+    #private;
+    /**
+     * Accounts API client.
+     * Provides methods for balances, transactions, relationships, NFTs, and token discovery.
+     */
+    readonly accounts: AccountsApiClient;
+    /**
+     * Prices API client.
+     * Provides methods for spot prices, exchange rates, and historical prices.
+     */
+    readonly prices: PricesApiClient;
+    /**
+     * Token API client.
+     * Provides methods for token metadata, networks, trending tokens, and top assets.
+     */
+    readonly token: TokenApiClient;
+    /**
+     * Tokens API client.
+     * Provides methods for bulk asset operations and supported networks.
+     */
+    readonly tokens: TokensApiClient;
+    constructor(options: ApiPlatformClientOptions);
+    /**
+     * Get the underlying QueryClient (for advanced usage).
+     *
+     * @returns The underlying QueryClient instance.
+     */
+    get queryClient(): QueryClient;
+    /**
+     * Get cached data for a query key.
+     *
+     * @param queryKey - The query key to look up.
+     * @returns The cached data or undefined.
+     */
+    getCachedData<CachedData>(queryKey: QueryKey): CachedData | undefined;
+    /**
+     * Set cached data for a query key.
+     *
+     * @param queryKey - The query key to set data for.
+     * @param data - The data to cache.
+     */
+    setCachedData<CachedData>(queryKey: QueryKey, data: CachedData): void;
+    /**
+     * Check if a query is currently fetching.
+     *
+     * @param queryKey - The query key to check.
+     * @returns True if the query is currently fetching.
+     */
+    isFetching(queryKey: QueryKey): boolean;
+    /**
+     * Clear all cached data across all sub-clients.
+     */
+    clear(): void;
+    /**
+     * Invalidate all queries across all sub-clients.
+     */
+    invalidateAll(): Promise<void>;
+    /**
+     * Invalidate the cached auth token.
+     * Call this when the user logs out or the token expires.
+     */
+    invalidateAuthToken(): Promise<void>;
+}
+/**
+ * Factory function to create an ApiPlatformClient.
+ *
+ * @param options - Configuration options for the client.
+ * @returns A new ApiPlatformClient instance.
+ */
+export declare function createApiPlatformClient(options: ApiPlatformClientOptions): ApiPlatformClient;
+//# sourceMappingURL=ApiPlatformClient.d.cts.map

package/dist/api/ApiPlatformClient.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ApiPlatformClient.d.cts","sourceRoot":"","sources":["../../src/api/ApiPlatformClient.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,EAAE,WAAW,EAAE,6BAA6B;AACnD,OAAO,KAAK,EAAE,QAAQ,EAAE,6BAA6B;AAGrD,OAAO,EAAE,iBAAiB,EAAE,6BAAmB;AAC/C,OAAO,EAAE,eAAe,EAAE,2BAAiB;AAQ3C,OAAO,KAAK,EAAE,wBAAwB,EAAE,2BAAuB;AAC/D,OAAO,EAAE,cAAc,EAAE,0BAAgB;AACzC,OAAO,EAAE,eAAe,EAAE,2BAAiB;AAM3C;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;;IAC5B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAC;IAErC;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;;OAGG;IACH,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAE/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;gBAOrB,OAAO,EAAE,wBAAwB;IAiC7C;;;;OAIG;IACH,IAAI,WAAW,IAAI,WAAW,CAE7B;IAED;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,GAAG,UAAU,GAAG,SAAS;IAIrE;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,UAAU,GAAG,IAAI;IAIrE;;;;;OAKG;IACH,UAAU,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO;IAIvC;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACG,aAAa,IAAI,OAAO,CAAC,IAAI,CAAC;IAIpC;;;OAGG;IACG,mBAAmB,IAAI,OAAO,CAAC,IAAI,CAAC;CAK3C;AAED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,wBAAwB,GAChC,iBAAiB,CAEnB"}