@tuwaio/orbit-core 0.1.2 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,17 +18,17 @@ Its primary goal is to establish a **unified interface** for interacting with di
18
18
 
19
19
  ## ✨ Key Features
20
20
 
21
- - **Multi-Chain Foundation:** Defines the core `OrbitAdapter` enum (supporting EVM, Solana, Starknet) and types for building consistent multi-chain support.
22
- - **Framework Agnostic & Headless:** Contains only logic, no UI components, ensuring compatibility with any frontend setup.
23
- - **Type-Safe Development:** Fully written in TypeScript 5.9+ for a robust developer experience.
24
- - **Flexible Adapter System:** Provides utilities like `selectAdapterByKey` to easily manage and switch between different blockchain adapter implementations.
25
- - **Essential Utilities:** Includes common helpers for tasks such as:
26
- * Formatting wallet names and chain IDs (`formatWalletName`, `formatWalletChainId`).
27
- * Identifying chain types (`isSolanaChain`, `getAdapterFromWalletType`).
28
- * Managing wallet connection state in localStorage (`lastConnectedWalletHelpers`, `recentConnectedWalletHelpers`).
29
- * Handling impersonation for development/testing (`impersonatedHelpers`).
30
- * Basic async operations (`delay`, `waitFor`).
31
- - **SSR Safe:** Utilities are designed to work safely in both browser and Server-Side Rendering environments.
21
+ - **Multi-Chain Foundation:** Defines the core `OrbitAdapter` enum (supporting EVM, Solana, Starknet) and types for building consistent multi-chain support.
22
+ - **Framework Agnostic & Headless:** Contains only logic, no UI components, ensuring compatibility with any frontend setup.
23
+ - **Type-Safe Development:** Fully written in TypeScript 5.9+ for a robust developer experience.
24
+ - **Flexible Adapter System:** Provides utilities like `selectAdapterByKey` to easily manage and switch between different blockchain adapter implementations.
25
+ - **Essential Utilities:** Includes common helpers for tasks such as:
26
+ - Formatting connector names and chain IDs (`formatConnectorName`, `formatConnectorChainId`).
27
+ - Identifying chain types (`isSolanaChain`, `getAdapterFromConnectorType`).
28
+ - Managing connector connection state in localStorage (`lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`).
29
+ - Handling impersonation for development/testing (`impersonatedHelpers`).
30
+ - Basic async operations (`delay`, `waitFor`).
31
+ - **SSR Safe:** Utilities are designed to work safely in both browser and Server-Side Rendering environments.
32
32
 
33
33
  ---
34
34
 
@@ -117,33 +117,33 @@ if (selectedSolanaAdapter && selectedSolanaAdapter.key === OrbitAdapter.SOLANA)
117
117
  ```typescript
118
118
  import {
119
119
  OrbitAdapter,
120
- formatWalletName,
121
- getAdapterFromWalletType,
122
- getWalletTypeFromConnectorName,
120
+ formatConnectorName,
121
+ getAdapterFromConnectorType,
122
+ getConnectorTypeFromName,
123
123
  isSolanaChain,
124
- lastConnectedWalletHelpers
124
+ lastConnectedConnectorHelpers
125
125
  } from '@tuwaio/orbit-core';
126
126
 
127
127
  // Formatting
128
- const formattedName = formatWalletName('MetaMask'); // "metamask"
128
+ const formattedName = formatConnectorName('MetaMask'); // "metamask"
129
129
  console.log(formattedName);
130
- const walletType = getWalletTypeFromConnectorName(OrbitAdapter.EVM, 'Brave Wallet'); // "evm:bravewallet"
131
- console.log(walletType);
130
+ const connectorType = getConnectorTypeFromName(OrbitAdapter.EVM, 'Brave Wallet'); // "evm:bravewallet"
131
+ console.log(connectorType);
132
132
 
133
133
  // Identification
134
- const adapterType = getAdapterFromWalletType(walletType); // OrbitAdapter.EVM
134
+ const adapterType = getAdapterFromConnectorType(connectorType); // OrbitAdapter.EVM
135
135
  console.log(adapterType);
136
136
  console.log(isSolanaChain('devnet')); // true
137
137
  console.log(isSolanaChain(1)); // false
138
138
 
139
- // Local Storage Management for Last Connected Wallet
140
- lastConnectedWalletHelpers.setLastConnectedWallet({
141
- walletType: 'evm:metamask',
139
+ // Local Storage Management for Last Connected Connector
140
+ lastConnectedConnectorHelpers.setLastConnectedConnector({
141
+ connectorType: 'evm:metamask',
142
142
  chainId: 1,
143
143
  address: '0x123...'
144
144
  });
145
- const lastWallet = lastConnectedWalletHelpers.getLastConnectedWallet();
146
- console.log(lastWallet); // { walletType: 'evm:metamask', chainId: 1, address: '0x123...' }
145
+ const lastWallet = lastConnectedConnectorHelpers.getLastConnectedConnector();
146
+ console.log(lastWallet); // { connectorType: 'evm:metamask', chainId: 1, address: '0x123...' }
147
147
 
148
148
  // lastConnectedWalletHelpers.removeLastConnectedWallet();
149
149
  ```
@@ -154,17 +154,17 @@ console.log(lastWallet); // { walletType: 'evm:metamask', chainId: 1, address: '
154
154
 
155
155
  Orbit Core is designed around modularity and abstraction:
156
156
 
157
- 1. **Core Types (`types.ts`):** Defines fundamental structures like `OrbitAdapter` (enum for EVM, Solana, Starknet), `BaseAdapter` (common interface), and `WalletType`.
158
- 2. **Adapter System:** Enables handling multiple blockchain types via a common interface. The `selectAdapterByKey` utility allows runtime selection of the correct adapter implementation based on the `OrbitAdapter` key. Chain-specific logic resides in separate packages (e.g., `@tuwaio/orbit-evm`).
159
- 3. **Utilities (`utils/`):** A collection of framework-agnostic helper functions covering formatting, chain identification, localStorage management (for connection state persistence), async operations, and other common tasks needed when building multi-chain UIs.
157
+ 1. **Core Types (`types.ts`):** Defines fundamental structures like `OrbitAdapter` (enum for EVM, Solana, Starknet), `BaseAdapter` (common interface), and `ConnectorType`.
158
+ 2. **Adapter System:** Enables handling multiple blockchain types via a common interface. The `selectAdapterByKey` utility allows runtime selection of the correct adapter implementation based on the `OrbitAdapter` key. Chain-specific logic resides in separate packages (e.g., `@tuwaio/orbit-evm`).
159
+ 3. **Utilities (`utils/`):** A collection of framework-agnostic helper functions covering formatting, chain identification, localStorage management (for connection state persistence), async operations, and other common tasks needed when building multi-chain UIs.
160
160
 
161
161
  ### Key Exports (`index.ts`)
162
162
 
163
- - **Types:** `OrbitAdapter`, `BaseAdapter`, `WalletType`, `OrbitGenericAdapter`, `RecentConnectedWallet`.
164
- - **Adapter Utilities:** `selectAdapterByKey`, `getAdapterFromWalletType`.
165
- - **Formatting Utilities:** `formatWalletChainId`, `formatWalletName`, `getWalletTypeFromConnectorName`.
163
+ - **Types:** `OrbitAdapter`, `BaseAdapter`, `ConnectorType`, `OrbitGenericAdapter`, `RecentConnectedConnector`.
164
+ - **Adapter Utilities:** `selectAdapterByKey`, `getAdapterFromConnectorType`.
165
+ - **Formatting Utilities:** `formatConnectorChainId`, `formatConnectorName`, `getConnectorTypeFromName`.
166
166
  - **Chain Helpers:** `isSolanaChain`, `setChainId`.
167
- - **Storage Helpers:** `lastConnectedWalletHelpers`, `recentConnectedWalletHelpers`, `impersonatedHelpers`, `getParsedStorageItem`.
167
+ - **Storage Helpers:** `lastConnectedConnectorHelpers`, `recentConnectedConnectorHelpers`, `impersonatedHelpers`, `getParsedStorageItem`.
168
168
  - **General Utilities:** `delay`, `filterUniqueByKey`, `waitFor`, `isSafeApp`.
169
169
 
170
170
  -----
package/dist/index.d.mts CHANGED
@@ -100,12 +100,14 @@ type BaseAdapter = {
100
100
  getName?: (address: string) => Promise<string | null>;
101
101
  /** Optional method to get avatar for resolved names */
102
102
  getAvatar?: (name: string) => Promise<string | null>;
103
+ /** Optional method to resolve names to addresses */
104
+ getAddress?: (name: string) => Promise<string | null>;
103
105
  };
104
106
  /**
105
- * Type representing a wallet identifier in format "OrbitAdapter:wallet"
107
+ * Type representing a connector identifier in format "OrbitAdapter:connector"
106
108
  * @example "evm:metamask" | "solana:phantom"
107
109
  */
108
- type WalletType = `${OrbitAdapter}:${string}`;
110
+ type ConnectorType = `${OrbitAdapter}:${string}`;
109
111
 
110
112
  /**
111
113
  * @name delay
@@ -152,69 +154,70 @@ declare const delay: <T>(value: T, ms: number) => Promise<T>;
152
154
  */
153
155
  declare function filterUniqueByKey<T>(array: T[], key: keyof T): T[];
154
156
 
155
- declare function formatWalletChainId(chainId: string | number, connectedAdapter: OrbitAdapter): string | number;
157
+ declare function formatConnectorChainId(chainId: string | number, connectedAdapter: OrbitAdapter): string | number;
156
158
 
157
- declare const formatWalletName: (walletName: string) => string;
159
+ declare const formatConnectorName: (connectorName: string) => string;
158
160
 
159
161
  /**
160
- * Extracts the adapter type from a wallet type string
162
+ * Extracts the adapter type from a connector type string
161
163
  *
162
164
  * @example
163
165
  * ```typescript
164
166
  * // Returns OrbitAdapter.EVM
165
- * getAdapterFromWalletType('evm:metamask');
167
+ * getAdapterFromConnectorType('evm:metamask');
166
168
  *
167
169
  * // Returns OrbitAdapter.SOLANA
168
- * getAdapterFromWalletType('solana:phantom');
170
+ * getAdapterFromConnectorType('solana:phantom');
169
171
  *
170
172
  * // Returns OrbitAdapter.EVM (default)
171
- * getAdapterFromWalletType('unknown');
173
+ * getAdapterFromConnectorType('unknown');
172
174
  * ```
173
175
  *
174
- * @param walletType - Wallet type in format "chain:wallet" (e.g. "evm:metamask", "solana:phantom")
176
+ * @param connectorType - Connector type in format "orbit-adapter:connector" (e.g. "evm:metamask", "solana:phantom")
175
177
  * @returns The corresponding {@link OrbitAdapter} type or EVM as default
176
178
  *
177
179
  * @remarks
178
- * The function splits the wallet type string by ":" and takes the first part as the adapter type.
180
+ * The function splits the connector type string by ":" and takes the first part as the adapter type.
179
181
  * If the split fails or the first part is empty, it defaults to EVM adapter.
180
182
  */
181
- declare function getAdapterFromWalletType(walletType: WalletType): OrbitAdapter;
183
+ declare function getAdapterFromConnectorType(connectorType: ConnectorType): OrbitAdapter;
182
184
 
183
185
  /**
184
- * Internal function for safely retrieving and parsing data from localStorage.
185
- *
186
- * @param key - The key for localStorage
187
- * @returns The parsed LastConnectedWallet object or undefined if data is not found/invalid
188
- */
189
- declare function getParsedStorageItem<ReturnType>(key: string): ReturnType | undefined;
190
-
191
- /**
192
- * Generates a standardized wallet type identifier from adapter type and connector name
186
+ * Generates a standardized connector type identifier from adapter type and connector name
193
187
  *
194
188
  * @example
195
189
  * ```typescript
196
190
  * // Returns "evm:metamask"
197
- * getWalletTypeFromConnectorName(OrbitAdapter.EVM, "MetaMask");
191
+ * getConnectorTypeFromName(OrbitAdapter.EVM, "MetaMask");
198
192
  *
199
193
  * // Returns "solana:phantom"
200
- * getWalletTypeFromConnectorName(OrbitAdapter.SOLANA, "Phantom");
194
+ * getConnectorTypeFromName(OrbitAdapter.SOLANA, "Phantom");
201
195
  *
202
196
  * // Returns "evm:coinbasewallet" (removes spaces)
203
- * getWalletTypeFromConnectorName(OrbitAdapter.EVM, "Coinbase Wallet");
197
+ * getConnectorTypeFromName(OrbitAdapter.EVM, "Coinbase Wallet");
204
198
  * ```
205
199
  *
206
200
  * @param adapter - The blockchain adapter type (e.g. EVM, SOLANA)
207
- * @param name - The wallet connector name (e.g. "MetaMask", "Phantom")
208
- * @returns A formatted wallet type string in format "chain:wallet"
201
+ * @param name - The connector name (e.g. "MetaMask", "Phantom")
202
+ * @returns A formatted connector type string in format "orbit-adapter:connector"
209
203
  *
210
204
  * @remarks
211
205
  * The function:
212
206
  * 1. Combines adapter type with connector name using ":" as separator
213
207
  * 2. Removes all whitespace from connector name
214
208
  * 3. Converts connector name to lowercase
215
- * This ensures consistent wallet type identifiers across the application
209
+ * This ensures consistent connector type identifiers across the application
210
+ * and normalizes connector names for better UX/consistency.
216
211
  */
217
- declare function getWalletTypeFromConnectorName(adapter: OrbitAdapter, name: string): string;
212
+ declare function getConnectorTypeFromName(adapter: OrbitAdapter, name: string): string;
213
+
214
+ /**
215
+ * Internal function for safely retrieving and parsing data from localStorage.
216
+ *
217
+ * @param key - The key for localStorage
218
+ * @returns The parsed LastConnectedConnector object or undefined if data is not found/invalid
219
+ */
220
+ declare function getParsedStorageItem<ReturnType>(key: string): ReturnType | undefined;
218
221
 
219
222
  /**
220
223
  * Helper utilities for managing impersonated wallet addresses
@@ -263,8 +266,8 @@ declare const impersonatedHelpers: {
263
266
 
264
267
  declare const isSafeApp: boolean;
265
268
 
266
- type LastConnectedWallet = {
267
- walletType: WalletType;
269
+ type LastConnectedConnector = {
270
+ connectorType: ConnectorType;
268
271
  chainId: number | string;
269
272
  address?: string;
270
273
  };
@@ -272,71 +275,269 @@ type LastConnectedWallet = {
272
275
  * Helper utilities for managing the last connected wallet state
273
276
  *
274
277
  * @remarks
275
- * All data is stored in localStorage with the 'orbit-core:lastConnectedWallet' key.
278
+ * All data is stored in localStorage with the 'orbit-core:lastConnectedConnector' key.
276
279
  * Functions are safe to use in both browser and SSR environments.
277
280
  */
278
- declare const lastConnectedWalletHelpers: {
281
+ declare const lastConnectedConnectorHelpers: {
279
282
  STORAGE_KEY: string;
280
283
  /**
281
284
  * The value of the last connected wallet, initialized when the module loads.
282
285
  * Returns undefined if not set, invalid, or in an SSR context.
283
286
  */
284
- lastConnectedWallet: LastConnectedWallet | undefined;
287
+ lastConnectedConnector: LastConnectedConnector | undefined;
285
288
  /**
286
289
  * Stores the last connected wallet data in localStorage.
287
290
  *
288
291
  * @param data - Object containing the wallet type and chain ID.
289
292
  * @returns undefined in SSR context, void in browser
290
293
  */
291
- setLastConnectedWallet: ({ walletType, chainId, address }: LastConnectedWallet) => void;
294
+ setLastConnectedConnector: ({ connectorType, chainId, address }: LastConnectedConnector) => void;
292
295
  /**
293
296
  * Retrieves the current last connected wallet data from localStorage.
294
297
  *
295
- * @returns The LastConnectedWallet object or undefined if not set or in SSR context
298
+ * @returns The LastConnectedConnector object or undefined if not set or in SSR context
296
299
  */
297
- getLastConnectedWallet: () => LastConnectedWallet | undefined;
300
+ getLastConnectedConnector: () => LastConnectedConnector | undefined;
298
301
  /**
299
302
  * Removes the last connected wallet data from localStorage.
300
303
  *
301
304
  * @returns undefined in SSR context, void in browser
302
305
  */
303
- removeLastConnectedWallet: () => void;
306
+ removeLastConnectedConnector: () => void;
304
307
  };
305
308
 
306
- type RecentConnectedWallet = Record<OrbitAdapter, Record<string, boolean>>;
307
309
  /**
308
- * Helper utilities for managing the last connected wallet state
310
+ * Data structure for a recently connected connector
311
+ *
312
+ * @interface RecentlyConnectedConnectorData
313
+ * @property {string} address - The wallet address that was connected
314
+ * @property {number} disconnectedTimestamp - Unix timestamp in milliseconds when the connector was disconnected
315
+ * @property {string} [icon] - Optional icon URL or identifier for the connector
316
+ */
317
+ type RecentlyConnectedConnectorData = {
318
+ address: string;
319
+ disconnectedTimestamp: number;
320
+ icon?: string;
321
+ };
322
+ /**
323
+ * Record mapping connector types to their recently connected data
324
+ *
325
+ * @type RecentlyConnectedConnectorsList
326
+ */
327
+ type RecentlyConnectedConnectorsList = Record<ConnectorType, RecentlyConnectedConnectorData>;
328
+ /**
329
+ * Helper utilities for managing recently connected connectors list with disconnect timestamps
309
330
  *
310
331
  * @remarks
311
- * All data is stored in localStorage with the 'orbit-core:lastConnectedWallet' key.
332
+ * All data is stored in localStorage with the 'orbit-core:recentlyConnectedConnectorsListHelpers' key.
312
333
  * Functions are safe to use in both browser and SSR environments.
334
+ *
335
+ * The storage contains a record where each key is a ConnectorType and value contains
336
+ * address, disconnectedTimestamp (Unix timestamp in milliseconds), and optional icon for that connector.
337
+ * This allows tracking when each connector was last disconnected for cleanup and sorting purposes.
338
+ *
339
+ * @example
340
+ * ```typescript
341
+ * // Set entire list
342
+ * recentlyConnectedConnectorsListHelpers.setRecentlyConnectedConnectorsList({
343
+ * 'evm:metamask': {
344
+ * address: '0x123...',
345
+ * disconnectedTimestamp: Date.now(),
346
+ * icon: 'metamask-icon.png'
347
+ * },
348
+ * 'solana:phantom': {
349
+ * address: 'ABC123...',
350
+ * disconnectedTimestamp: Date.now() - 3600000, // 1 hour ago
351
+ * icon: 'phantom-icon.png'
352
+ * }
353
+ * });
354
+ *
355
+ * // Add single connector
356
+ * recentlyConnectedConnectorsListHelpers.addConnector('evm:walletconnect', {
357
+ * address: '0x456...',
358
+ * disconnectedTimestamp: Date.now(),
359
+ * icon: 'walletconnect-icon.png'
360
+ * });
361
+ *
362
+ * // Remove single connector
363
+ * recentlyConnectedConnectorsListHelpers.removeConnector('evm:metamask');
364
+ * ```
313
365
  */
314
- declare const recentConnectedWalletHelpers: {
366
+ declare const recentlyConnectedConnectorsListHelpers: {
367
+ /** Key used for localStorage storage */
315
368
  STORAGE_KEY: string;
316
369
  /**
317
- * The value of the last connected wallet, initialized when the module loads.
370
+ * The current recently connected connectors list, initialized when the module loads.
318
371
  * Returns undefined if not set, invalid, or in an SSR context.
372
+ *
373
+ * @readonly
319
374
  */
320
- recentConnectedWallet: RecentConnectedWallet | undefined;
375
+ recentlyConnectedConnectorsList: RecentlyConnectedConnectorsList | undefined;
321
376
  /**
322
- * Stores the last connected wallet data in localStorage.
377
+ * Stores the complete recently connected connectors list in localStorage.
378
+ * This will overwrite the entire existing list.
323
379
  *
324
- * @param wallets - RecentConnectedWallet
380
+ * @param connectors - Complete RecentlyConnectedConnectorsList object
325
381
  * @returns undefined in SSR context, void in browser
382
+ *
383
+ * @example
384
+ * ```typescript
385
+ * recentlyConnectedConnectorsListHelpers.setRecentlyConnectedConnectorsList({
386
+ * 'evm:metamask': {
387
+ * address: '0x123...',
388
+ * disconnectedTimestamp: Date.now(),
389
+ * icon: 'metamask.png'
390
+ * },
391
+ * 'solana:phantom': {
392
+ * address: 'ABC123...',
393
+ * disconnectedTimestamp: Date.now() - 1800000 // 30 minutes ago
394
+ * }
395
+ * });
396
+ * ```
326
397
  */
327
- setRecentConnectedWallet: (wallets: RecentConnectedWallet) => void;
398
+ setRecentlyConnectedConnectorsList: (connectors: RecentlyConnectedConnectorsList) => void;
328
399
  /**
329
- * Retrieves the current last connected wallet data from localStorage.
400
+ * Retrieves the current recently connected connectors list from localStorage.
330
401
  *
331
- * @returns The LastConnectedWallet object or undefined if not set or in SSR context
402
+ * @returns The RecentlyConnectedConnectorsList object or undefined if not set or in SSR context
403
+ *
404
+ * @example
405
+ * ```typescript
406
+ * const connectors = recentlyConnectedConnectorsListHelpers.getRecentlyConnectedConnectorsList();
407
+ * if (connectors) {
408
+ * console.log('Available connectors:', Object.keys(connectors));
409
+ * // Sort by most recently disconnected
410
+ * const sorted = Object.entries(connectors)
411
+ * .sort(([,a], [,b]) => b.disconnectedTimestamp - a.disconnectedTimestamp);
412
+ * }
413
+ * ```
332
414
  */
333
- getRecentConnectedWallet: () => RecentConnectedWallet | undefined;
415
+ getRecentlyConnectedConnectorsList: () => RecentlyConnectedConnectorsList | undefined;
334
416
  /**
335
- * Removes the last connected wallet data from localStorage.
417
+ * Adds or updates a single connector in the recently connected connectors list.
418
+ * Preserves existing connectors and only adds/updates the specified one.
336
419
  *
420
+ * @param connectorType - The connector type to add/update
421
+ * @param connectorData - The connector data (address, disconnectedTimestamp, and optional icon)
337
422
  * @returns undefined in SSR context, void in browser
423
+ *
424
+ * @example
425
+ * ```typescript
426
+ * // Add new connector with current timestamp
427
+ * recentlyConnectedConnectorsListHelpers.addConnector('evm:metamask', {
428
+ * address: '0x123...',
429
+ * disconnectedTimestamp: Date.now(),
430
+ * icon: 'metamask.png'
431
+ * });
432
+ *
433
+ * // Update existing connector with new disconnect time
434
+ * recentlyConnectedConnectorsListHelpers.addConnector('evm:metamask', {
435
+ * address: '0x456...',
436
+ * disconnectedTimestamp: Date.now(),
437
+ * icon: 'new-metamask.png'
438
+ * });
439
+ * ```
440
+ */
441
+ addConnector: (connectorType: ConnectorType, connectorData: RecentlyConnectedConnectorData) => undefined;
442
+ /**
443
+ * Removes a single connector from the recently connected connectors list.
444
+ * Preserves all other connectors in the list.
445
+ *
446
+ * @param connectorType - The connector type to remove
447
+ * @returns undefined in SSR context, void in browser
448
+ *
449
+ * @example
450
+ * ```typescript
451
+ * // Remove specific connector
452
+ * recentlyConnectedConnectorsListHelpers.removeConnector('evm:metamask');
453
+ * ```
454
+ */
455
+ removeConnector: (connectorType: ConnectorType) => undefined;
456
+ /**
457
+ * Checks if a specific connector exists in the recently connected connectors list.
458
+ *
459
+ * @param connectorType - The connector type to check
460
+ * @returns true if the connector exists, false otherwise, undefined in SSR context
461
+ *
462
+ * @example
463
+ * ```typescript
464
+ * if (recentlyConnectedConnectorsListHelpers.hasConnector('evm:metamask')) {
465
+ * console.log('MetaMask was recently connected');
466
+ * }
467
+ * ```
468
+ */
469
+ hasConnector: (connectorType: ConnectorType) => boolean | undefined;
470
+ /**
471
+ * Gets data for a specific connector from the recently connected connectors list.
472
+ *
473
+ * @param connectorType - The connector type to get data for
474
+ * @returns The connector data (including address, disconnectedTimestamp, and optional icon) or undefined if not found or in SSR context
475
+ *
476
+ * @example
477
+ * ```typescript
478
+ * const metamaskData = recentlyConnectedConnectorsListHelpers.getConnector('evm:metamask');
479
+ * if (metamaskData) {
480
+ * console.log('MetaMask address:', metamaskData.address);
481
+ * console.log('Disconnected at:', new Date(metamaskData.disconnectedTimestamp));
482
+ * console.log('MetaMask icon:', metamaskData.icon);
483
+ * }
484
+ * ```
485
+ */
486
+ getConnector: (connectorType: ConnectorType) => RecentlyConnectedConnectorData | undefined;
487
+ /**
488
+ * Gets the count of recently connected connectors.
489
+ *
490
+ * @returns Number of connectors in the list, 0 in SSR context or if list is empty
491
+ *
492
+ * @example
493
+ * ```typescript
494
+ * const count = recentlyConnectedConnectorsListHelpers.getConnectorCount();
495
+ * console.log(`${count} connectors recently connected`);
496
+ * ```
497
+ */
498
+ getConnectorCount: () => number;
499
+ /**
500
+ * Gets recently connected connectors sorted by disconnect time (most recent first).
501
+ * Useful for showing connectors in order of recent usage.
502
+ *
503
+ * @returns Array of [ConnectorType, RecentlyConnectedConnectorData] tuples sorted by disconnectedTimestamp (descending), empty array in SSR context
504
+ *
505
+ * @example
506
+ * ```typescript
507
+ * const sortedConnectors = recentlyConnectedConnectorsListHelpers.getConnectorsSortedByTime();
508
+ * sortedConnectors.forEach(([connectorType, data]) => {
509
+ * console.log(`${connectorType}: disconnected ${new Date(data.disconnectedTimestamp)}`);
510
+ * });
511
+ * ```
512
+ */
513
+ getConnectorsSortedByTime: () => [ConnectorType, RecentlyConnectedConnectorData][];
514
+ /**
515
+ * Removes connectors that were disconnected before the specified timestamp.
516
+ * Useful for cleaning up old connector entries.
517
+ *
518
+ * @param beforeTimestamp - Unix timestamp in milliseconds; connectors disconnected before this time will be removed
519
+ * @returns undefined in SSR context, void in browser
520
+ *
521
+ * @example
522
+ * ```typescript
523
+ * // Remove connectors disconnected more than 7 days ago
524
+ * const weekAgo = Date.now() - (7 * 24 * 60 * 60 * 1000);
525
+ * recentlyConnectedConnectorsListHelpers.removeConnectorsOlderThan(weekAgo);
526
+ * ```
527
+ */
528
+ removeConnectorsOlderThan: (beforeTimestamp: number) => undefined;
529
+ /**
530
+ * Removes all recently connected connectors from localStorage.
531
+ *
532
+ * @returns undefined in SSR context, void in browser
533
+ *
534
+ * @example
535
+ * ```typescript
536
+ * // Clear all recently connected connectors
537
+ * recentlyConnectedConnectorsListHelpers.removeRecentlyConnectedConnectorsList();
538
+ * ```
338
539
  */
339
- removeRecentConnectedWallet: () => void;
540
+ removeRecentlyConnectedConnectorsList: () => void;
340
541
  };
341
542
 
342
543
  /**
@@ -406,4 +607,4 @@ declare function isSolanaChain(chainId: number | string): boolean;
406
607
  */
407
608
  declare function setChainId(chainId: number | string): string | number;
408
609
 
409
- export { type BaseAdapter, OrbitAdapter, type OrbitGenericAdapter, type RecentConnectedWallet, type WalletType, delay, filterUniqueByKey, formatWalletChainId, formatWalletName, getAdapterFromWalletType, getParsedStorageItem, getWalletTypeFromConnectorName, impersonatedHelpers, isSafeApp, isSolanaChain, lastConnectedWalletHelpers, recentConnectedWalletHelpers, selectAdapterByKey, setChainId, waitFor };
610
+ export { type BaseAdapter, type ConnectorType, OrbitAdapter, type OrbitGenericAdapter, type RecentlyConnectedConnectorData, type RecentlyConnectedConnectorsList, delay, filterUniqueByKey, formatConnectorChainId, formatConnectorName, getAdapterFromConnectorType, getConnectorTypeFromName, getParsedStorageItem, impersonatedHelpers, isSafeApp, isSolanaChain, lastConnectedConnectorHelpers, recentlyConnectedConnectorsListHelpers, selectAdapterByKey, setChainId, waitFor };