@lombard.finance/sdk-devtools 0.1.0-canary.0.4
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/LICENSE +21 -0
- package/README.md +344 -0
- package/dist/index.d.ts +830 -0
- package/dist/index.js +1509 -0
- package/dist/index.js.map +1 -0
- package/package.json +70 -0
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,830 @@
|
|
|
1
|
+
import * as react_jsx_runtime from 'react/jsx-runtime';
|
|
2
|
+
import { ReactNode } from 'react';
|
|
3
|
+
|
|
4
|
+
/**
|
|
5
|
+
* SDK DevTools - Type Definitions
|
|
6
|
+
*
|
|
7
|
+
* Core types for the Lombard SDK DevTools package.
|
|
8
|
+
* These are framework-agnostic and can be used with any UI framework.
|
|
9
|
+
*/
|
|
10
|
+
/**
|
|
11
|
+
* Represents an event emitted by the SDK
|
|
12
|
+
*/
|
|
13
|
+
interface DevToolsEvent {
|
|
14
|
+
/** Unique event ID */
|
|
15
|
+
id: string;
|
|
16
|
+
/** Event type (e.g., 'status-change', 'error', 'completed') */
|
|
17
|
+
type: string;
|
|
18
|
+
/** Unix timestamp when event occurred */
|
|
19
|
+
timestamp: number;
|
|
20
|
+
/** Event payload data */
|
|
21
|
+
data: unknown;
|
|
22
|
+
/** Source action name (e.g., 'BtcStake', 'EvmUnstake') */
|
|
23
|
+
source?: string;
|
|
24
|
+
/** Whether this event came from the SDK's built-in event emitter */
|
|
25
|
+
isSDKEvent: boolean;
|
|
26
|
+
}
|
|
27
|
+
/**
|
|
28
|
+
* Log entry for reducer actions (Redux DevTools style)
|
|
29
|
+
*/
|
|
30
|
+
interface ReducerLogEntry {
|
|
31
|
+
/** Unique log ID */
|
|
32
|
+
id: string;
|
|
33
|
+
/** Unix timestamp when action was dispatched */
|
|
34
|
+
timestamp: number;
|
|
35
|
+
/** The dispatched action */
|
|
36
|
+
action: {
|
|
37
|
+
type: string;
|
|
38
|
+
payload?: unknown;
|
|
39
|
+
};
|
|
40
|
+
/** State before action */
|
|
41
|
+
prevState: unknown;
|
|
42
|
+
/** State after action */
|
|
43
|
+
nextState: unknown;
|
|
44
|
+
}
|
|
45
|
+
/**
|
|
46
|
+
* Minimal interface for monitorable SDK actions
|
|
47
|
+
* Matches the SDK's MonitorableAction interface
|
|
48
|
+
*/
|
|
49
|
+
interface MonitorableAction {
|
|
50
|
+
/** Current status of the action */
|
|
51
|
+
readonly status: string;
|
|
52
|
+
/** Whether an async operation is in progress */
|
|
53
|
+
readonly isLoading: boolean;
|
|
54
|
+
/** Error that occurred (if any) */
|
|
55
|
+
readonly error: Error | null;
|
|
56
|
+
/** Whether the action has failed */
|
|
57
|
+
readonly isFailed: boolean;
|
|
58
|
+
/** Subscribe to events */
|
|
59
|
+
on(event: string, handler: (...args: unknown[]) => void): () => void;
|
|
60
|
+
}
|
|
61
|
+
/**
|
|
62
|
+
* Registered action with metadata
|
|
63
|
+
*/
|
|
64
|
+
interface RegisteredAction {
|
|
65
|
+
/** Unique name for this action instance */
|
|
66
|
+
name: string;
|
|
67
|
+
/** The action instance */
|
|
68
|
+
action: MonitorableAction;
|
|
69
|
+
/** When the action was registered */
|
|
70
|
+
registeredAt: number;
|
|
71
|
+
/** Category (btc, evm, solana, etc.) */
|
|
72
|
+
category?: string;
|
|
73
|
+
}
|
|
74
|
+
/**
|
|
75
|
+
* Represents a step in an action flow
|
|
76
|
+
*/
|
|
77
|
+
interface FlowStep {
|
|
78
|
+
/** Step identifier */
|
|
79
|
+
id: string;
|
|
80
|
+
/** Display label */
|
|
81
|
+
label: string;
|
|
82
|
+
/** Optional description */
|
|
83
|
+
description?: string;
|
|
84
|
+
/** Step status */
|
|
85
|
+
status: 'pending' | 'current' | 'completed' | 'error';
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Position options for the floating widget
|
|
89
|
+
*/
|
|
90
|
+
type DevToolsPosition = 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left';
|
|
91
|
+
/**
|
|
92
|
+
* Theme options for DevTools
|
|
93
|
+
*/
|
|
94
|
+
type DevToolsTheme = 'dark' | 'light' | 'system';
|
|
95
|
+
/**
|
|
96
|
+
* Configuration options for DevTools
|
|
97
|
+
*/
|
|
98
|
+
interface DevToolsConfig {
|
|
99
|
+
/** Widget position on screen */
|
|
100
|
+
position?: DevToolsPosition;
|
|
101
|
+
/** Whether to start open or collapsed */
|
|
102
|
+
defaultOpen?: boolean;
|
|
103
|
+
/** Theme preference */
|
|
104
|
+
theme?: DevToolsTheme;
|
|
105
|
+
/** Show environment indicator */
|
|
106
|
+
showEnvironment?: boolean;
|
|
107
|
+
/** Enable console logging alongside widget */
|
|
108
|
+
consoleLogging?: boolean;
|
|
109
|
+
/** Maximum number of events to retain */
|
|
110
|
+
maxEvents?: number;
|
|
111
|
+
/** Maximum number of reducer logs to retain */
|
|
112
|
+
maxReducerLogs?: number;
|
|
113
|
+
}
|
|
114
|
+
/**
|
|
115
|
+
* Default DevTools configuration
|
|
116
|
+
*/
|
|
117
|
+
declare const DEFAULT_DEVTOOLS_CONFIG: Required<DevToolsConfig>;
|
|
118
|
+
/**
|
|
119
|
+
* Mock addresses for testing without real wallets
|
|
120
|
+
*/
|
|
121
|
+
interface MockAddresses {
|
|
122
|
+
evm: string;
|
|
123
|
+
bitcoin: string;
|
|
124
|
+
solana: string;
|
|
125
|
+
sui: string;
|
|
126
|
+
starknet: string;
|
|
127
|
+
}
|
|
128
|
+
/**
|
|
129
|
+
* Mock wallet state and controls
|
|
130
|
+
*/
|
|
131
|
+
interface MockWalletState {
|
|
132
|
+
/** Whether mock wallet is enabled */
|
|
133
|
+
isEnabled: boolean;
|
|
134
|
+
/** Current mock address (based on chain type) */
|
|
135
|
+
address: string;
|
|
136
|
+
/** Current mock chain ID */
|
|
137
|
+
chainId: number;
|
|
138
|
+
/** Whether mock wallet can sign (always false) */
|
|
139
|
+
canSign: boolean;
|
|
140
|
+
/** Enable mock wallet */
|
|
141
|
+
enable: () => void;
|
|
142
|
+
/** Disable mock wallet */
|
|
143
|
+
disable: () => void;
|
|
144
|
+
/** Toggle mock wallet */
|
|
145
|
+
toggle: () => void;
|
|
146
|
+
/** Set mock chain */
|
|
147
|
+
setChain: (chainId: number) => void;
|
|
148
|
+
/** Get mock address for a specific chain type */
|
|
149
|
+
getAddress: (chainType: keyof MockAddresses) => string;
|
|
150
|
+
}
|
|
151
|
+
/**
|
|
152
|
+
* Warning severity levels
|
|
153
|
+
*/
|
|
154
|
+
type WarningSeverity = 'info' | 'warning' | 'error';
|
|
155
|
+
/**
|
|
156
|
+
* DevTools warning message
|
|
157
|
+
*/
|
|
158
|
+
interface DevToolsWarning {
|
|
159
|
+
/** Unique warning ID */
|
|
160
|
+
id: string;
|
|
161
|
+
/** Warning severity */
|
|
162
|
+
severity: WarningSeverity;
|
|
163
|
+
/** Warning title */
|
|
164
|
+
title: string;
|
|
165
|
+
/** Warning message */
|
|
166
|
+
message: string;
|
|
167
|
+
/** Link to documentation */
|
|
168
|
+
docsLink?: string;
|
|
169
|
+
/** Suggested code fix */
|
|
170
|
+
suggestedFix?: string;
|
|
171
|
+
/** When the warning was triggered */
|
|
172
|
+
timestamp: number;
|
|
173
|
+
}
|
|
174
|
+
/**
|
|
175
|
+
* HTTP method types
|
|
176
|
+
*/
|
|
177
|
+
type HttpMethod = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH';
|
|
178
|
+
/**
|
|
179
|
+
* API request event - logged when a request is initiated
|
|
180
|
+
*/
|
|
181
|
+
interface ApiRequestEvent {
|
|
182
|
+
/** Unique request ID */
|
|
183
|
+
id: string;
|
|
184
|
+
/** Event type */
|
|
185
|
+
type: 'api-request';
|
|
186
|
+
/** HTTP method */
|
|
187
|
+
method: HttpMethod;
|
|
188
|
+
/** Request URL (full or relative) */
|
|
189
|
+
url: string;
|
|
190
|
+
/** Request payload (body or params) */
|
|
191
|
+
payload?: unknown;
|
|
192
|
+
/** Request headers (selected) */
|
|
193
|
+
headers?: Record<string, string>;
|
|
194
|
+
/** When the request was initiated */
|
|
195
|
+
timestamp: number;
|
|
196
|
+
/** Source/origin of the request (e.g., 'api.deposits', 'btc.stake') */
|
|
197
|
+
source?: string;
|
|
198
|
+
}
|
|
199
|
+
/**
|
|
200
|
+
* API response event - logged when a response is received
|
|
201
|
+
*/
|
|
202
|
+
interface ApiResponseEvent {
|
|
203
|
+
/** Unique response ID */
|
|
204
|
+
id: string;
|
|
205
|
+
/** Event type */
|
|
206
|
+
type: 'api-response';
|
|
207
|
+
/** Corresponding request ID */
|
|
208
|
+
requestId: string;
|
|
209
|
+
/** HTTP status code */
|
|
210
|
+
status: number;
|
|
211
|
+
/** Status text (e.g., 'OK', 'Not Found') */
|
|
212
|
+
statusText?: string;
|
|
213
|
+
/** Response data (parsed) */
|
|
214
|
+
data?: unknown;
|
|
215
|
+
/** Error message if request failed */
|
|
216
|
+
error?: string;
|
|
217
|
+
/** Request duration in milliseconds */
|
|
218
|
+
duration: number;
|
|
219
|
+
/** When the response was received */
|
|
220
|
+
timestamp: number;
|
|
221
|
+
}
|
|
222
|
+
/**
|
|
223
|
+
* Combined API event for the Network log
|
|
224
|
+
*/
|
|
225
|
+
interface NetworkLogEntry {
|
|
226
|
+
/** Request details */
|
|
227
|
+
request: ApiRequestEvent;
|
|
228
|
+
/** Response details (null if pending) */
|
|
229
|
+
response: ApiResponseEvent | null;
|
|
230
|
+
/** Whether the request is still pending */
|
|
231
|
+
isPending: boolean;
|
|
232
|
+
/** Whether the request failed */
|
|
233
|
+
isFailed: boolean;
|
|
234
|
+
}
|
|
235
|
+
|
|
236
|
+
/**
|
|
237
|
+
* DevToolsBridge - Connects SDK actions to DevTools automatically
|
|
238
|
+
*
|
|
239
|
+
* This is the core integration layer that makes DevTools "just work"
|
|
240
|
+
* with the Lombard SDK. It automatically subscribes to action events
|
|
241
|
+
* and provides the collected data to DevTools components.
|
|
242
|
+
*
|
|
243
|
+
* ## How It Works
|
|
244
|
+
*
|
|
245
|
+
* 1. Wrap the SDK at initialization
|
|
246
|
+
* 2. Automatically intercept action creation
|
|
247
|
+
* 3. Subscribe to all action events
|
|
248
|
+
* 4. Aggregate events/state for DevTools display
|
|
249
|
+
*
|
|
250
|
+
* @module sdk-devtools/bridge
|
|
251
|
+
*/
|
|
252
|
+
|
|
253
|
+
type DevToolsEventCallback = (event: DevToolsEvent) => void;
|
|
254
|
+
type DevToolsStateCallback = (actions: Map<string, RegisteredAction>) => void;
|
|
255
|
+
/**
|
|
256
|
+
* DevToolsBridge - Collects events from all SDK actions
|
|
257
|
+
*
|
|
258
|
+
* Usage:
|
|
259
|
+
* ```typescript
|
|
260
|
+
* // Create bridge
|
|
261
|
+
* const bridge = new DevToolsBridge();
|
|
262
|
+
*
|
|
263
|
+
* // Register an action
|
|
264
|
+
* const stake = sdk.btc.stake({ ... });
|
|
265
|
+
* bridge.registerAction('btc-stake', stake);
|
|
266
|
+
*
|
|
267
|
+
* // Subscribe to events
|
|
268
|
+
* const unsubscribe = bridge.onEvent((event) => {
|
|
269
|
+
* console.log('SDK Event:', event);
|
|
270
|
+
* });
|
|
271
|
+
*
|
|
272
|
+
* // Get all events
|
|
273
|
+
* const events = bridge.getEvents();
|
|
274
|
+
*
|
|
275
|
+
* // Get registered actions
|
|
276
|
+
* const actions = bridge.getActions();
|
|
277
|
+
* ```
|
|
278
|
+
*/
|
|
279
|
+
declare class DevToolsBridge {
|
|
280
|
+
private events;
|
|
281
|
+
private actions;
|
|
282
|
+
private unsubscribers;
|
|
283
|
+
private eventListeners;
|
|
284
|
+
private stateListeners;
|
|
285
|
+
private config;
|
|
286
|
+
private eventIdCounter;
|
|
287
|
+
private networkLog;
|
|
288
|
+
private networkListeners;
|
|
289
|
+
private requestIdCounter;
|
|
290
|
+
constructor(config?: DevToolsConfig);
|
|
291
|
+
/**
|
|
292
|
+
* Register an SDK action for monitoring
|
|
293
|
+
*
|
|
294
|
+
* Automatically subscribes to all standard events:
|
|
295
|
+
* - status-change
|
|
296
|
+
* - error
|
|
297
|
+
* - completed
|
|
298
|
+
* - failed
|
|
299
|
+
* - loading
|
|
300
|
+
* - progress
|
|
301
|
+
*/
|
|
302
|
+
registerAction(name: string, action: MonitorableAction, options?: {
|
|
303
|
+
category?: string;
|
|
304
|
+
}): () => void;
|
|
305
|
+
/**
|
|
306
|
+
* Unregister an action
|
|
307
|
+
*/
|
|
308
|
+
unregisterAction(name: string): void;
|
|
309
|
+
private handleEvent;
|
|
310
|
+
private notifyEventListeners;
|
|
311
|
+
private notifyStateListeners;
|
|
312
|
+
/**
|
|
313
|
+
* Subscribe to new events
|
|
314
|
+
*/
|
|
315
|
+
onEvent(callback: DevToolsEventCallback): () => void;
|
|
316
|
+
/**
|
|
317
|
+
* Subscribe to action state changes
|
|
318
|
+
*/
|
|
319
|
+
onStateChange(callback: DevToolsStateCallback): () => void;
|
|
320
|
+
/**
|
|
321
|
+
* Get all collected events
|
|
322
|
+
*/
|
|
323
|
+
getEvents(): DevToolsEvent[];
|
|
324
|
+
/**
|
|
325
|
+
* Get all registered actions
|
|
326
|
+
*/
|
|
327
|
+
getActions(): Map<string, RegisteredAction>;
|
|
328
|
+
/**
|
|
329
|
+
* Get current state summary for all actions
|
|
330
|
+
*/
|
|
331
|
+
getStateSummary(): Record<string, {
|
|
332
|
+
status: string;
|
|
333
|
+
isLoading: boolean;
|
|
334
|
+
hasError: boolean;
|
|
335
|
+
}>;
|
|
336
|
+
/**
|
|
337
|
+
* Log an API request
|
|
338
|
+
*
|
|
339
|
+
* Call this when an HTTP request is initiated.
|
|
340
|
+
* Returns a request ID to correlate with the response.
|
|
341
|
+
*/
|
|
342
|
+
logApiRequest(params: {
|
|
343
|
+
method: HttpMethod;
|
|
344
|
+
url: string;
|
|
345
|
+
payload?: unknown;
|
|
346
|
+
headers?: Record<string, string>;
|
|
347
|
+
source?: string;
|
|
348
|
+
}): string;
|
|
349
|
+
/**
|
|
350
|
+
* Log an API response
|
|
351
|
+
*
|
|
352
|
+
* Call this when an HTTP response is received.
|
|
353
|
+
* Pass the requestId returned from logApiRequest.
|
|
354
|
+
*/
|
|
355
|
+
logApiResponse(params: {
|
|
356
|
+
requestId: string;
|
|
357
|
+
status: number;
|
|
358
|
+
statusText?: string;
|
|
359
|
+
data?: unknown;
|
|
360
|
+
error?: string;
|
|
361
|
+
}): void;
|
|
362
|
+
/**
|
|
363
|
+
* Subscribe to network log changes
|
|
364
|
+
*/
|
|
365
|
+
onNetworkChange(callback: (entries: NetworkLogEntry[]) => void): () => void;
|
|
366
|
+
/**
|
|
367
|
+
* Get all network log entries
|
|
368
|
+
*/
|
|
369
|
+
getNetworkLog(): NetworkLogEntry[];
|
|
370
|
+
/**
|
|
371
|
+
* Clear network log
|
|
372
|
+
*/
|
|
373
|
+
clearNetworkLog(): void;
|
|
374
|
+
private notifyNetworkListeners;
|
|
375
|
+
/**
|
|
376
|
+
* Clear all events
|
|
377
|
+
*/
|
|
378
|
+
clearEvents(): void;
|
|
379
|
+
/**
|
|
380
|
+
* Clear all registered actions
|
|
381
|
+
*/
|
|
382
|
+
clearActions(): void;
|
|
383
|
+
/**
|
|
384
|
+
* Destroy the bridge
|
|
385
|
+
*/
|
|
386
|
+
destroy(): void;
|
|
387
|
+
}
|
|
388
|
+
/**
|
|
389
|
+
* Get or create the global DevTools bridge
|
|
390
|
+
*/
|
|
391
|
+
declare function getDevToolsBridge(config?: DevToolsConfig): DevToolsBridge;
|
|
392
|
+
/**
|
|
393
|
+
* Reset the global DevTools bridge
|
|
394
|
+
*/
|
|
395
|
+
declare function resetDevToolsBridge(): void;
|
|
396
|
+
|
|
397
|
+
interface DevToolsContextValue {
|
|
398
|
+
/** All collected events */
|
|
399
|
+
events: DevToolsEvent[];
|
|
400
|
+
/** All registered actions */
|
|
401
|
+
actions: Map<string, RegisteredAction>;
|
|
402
|
+
/** Network log entries (API requests/responses) */
|
|
403
|
+
networkLog: NetworkLogEntry[];
|
|
404
|
+
/** Register an action for monitoring */
|
|
405
|
+
registerAction: (name: string, action: MonitorableAction, options?: {
|
|
406
|
+
category?: string;
|
|
407
|
+
}) => () => void;
|
|
408
|
+
/** Unregister an action */
|
|
409
|
+
unregisterAction: (name: string) => void;
|
|
410
|
+
/** Clear all events */
|
|
411
|
+
clearEvents: () => void;
|
|
412
|
+
/** Clear network log */
|
|
413
|
+
clearNetworkLog: () => void;
|
|
414
|
+
/** Get current state of all actions */
|
|
415
|
+
getStateSummary: () => Record<string, {
|
|
416
|
+
status: string;
|
|
417
|
+
isLoading: boolean;
|
|
418
|
+
hasError: boolean;
|
|
419
|
+
}>;
|
|
420
|
+
/** The underlying bridge instance */
|
|
421
|
+
bridge: DevToolsBridge;
|
|
422
|
+
/** Whether DevTools is enabled */
|
|
423
|
+
isEnabled: boolean;
|
|
424
|
+
}
|
|
425
|
+
interface DevToolsProviderProps {
|
|
426
|
+
children: ReactNode;
|
|
427
|
+
/** DevTools configuration */
|
|
428
|
+
config?: DevToolsConfig;
|
|
429
|
+
/**
|
|
430
|
+
* Whether DevTools is enabled.
|
|
431
|
+
*
|
|
432
|
+
* Default: `process.env.NODE_ENV !== 'production'`
|
|
433
|
+
*
|
|
434
|
+
* For development/testing tools (like sdk-demo), you may want to always
|
|
435
|
+
* enable DevTools with `enabled={true}` regardless of environment, so
|
|
436
|
+
* developers can debug production SDK endpoints.
|
|
437
|
+
*/
|
|
438
|
+
enabled?: boolean;
|
|
439
|
+
}
|
|
440
|
+
/**
|
|
441
|
+
* DevTools Provider
|
|
442
|
+
*
|
|
443
|
+
* Wrap your app with this provider to enable DevTools functionality.
|
|
444
|
+
*
|
|
445
|
+
* The `enabled` prop defaults to `false` in production (NODE_ENV === 'production')
|
|
446
|
+
* as a safety net. However, you can explicitly override this:
|
|
447
|
+
* - `enabled={true}` - Always enable (useful for dev tools testing prod SDK)
|
|
448
|
+
* - `enabled={false}` - Always disable
|
|
449
|
+
*
|
|
450
|
+
* @example
|
|
451
|
+
* ```tsx
|
|
452
|
+
* // Basic usage - auto-disabled in production builds
|
|
453
|
+
* function App() {
|
|
454
|
+
* return (
|
|
455
|
+
* <DevToolsProvider>
|
|
456
|
+
* <MyApp />
|
|
457
|
+
* </DevToolsProvider>
|
|
458
|
+
* );
|
|
459
|
+
* }
|
|
460
|
+
*
|
|
461
|
+
* // Always enable (for developer tools/playgrounds)
|
|
462
|
+
* function DevToolApp() {
|
|
463
|
+
* return (
|
|
464
|
+
* <DevToolsProvider enabled={true}>
|
|
465
|
+
* <MyApp />
|
|
466
|
+
* </DevToolsProvider>
|
|
467
|
+
* );
|
|
468
|
+
* }
|
|
469
|
+
* ```
|
|
470
|
+
*/
|
|
471
|
+
declare function DevToolsProvider({ children, config, enabled, }: DevToolsProviderProps): react_jsx_runtime.JSX.Element;
|
|
472
|
+
/**
|
|
473
|
+
* Hook to access DevTools context
|
|
474
|
+
*
|
|
475
|
+
* @example
|
|
476
|
+
* ```tsx
|
|
477
|
+
* function MyComponent() {
|
|
478
|
+
* const { registerAction, events } = useDevToolsContext();
|
|
479
|
+
*
|
|
480
|
+
* useEffect(() => {
|
|
481
|
+
* const action = sdk.btc.stake({ ... });
|
|
482
|
+
* return registerAction('stake', action);
|
|
483
|
+
* }, []);
|
|
484
|
+
*
|
|
485
|
+
* return <div>Events: {events.length}</div>;
|
|
486
|
+
* }
|
|
487
|
+
* ```
|
|
488
|
+
*/
|
|
489
|
+
declare function useDevToolsContext(): DevToolsContextValue;
|
|
490
|
+
/**
|
|
491
|
+
* Hook to register an action with DevTools (from within context)
|
|
492
|
+
*
|
|
493
|
+
* @example
|
|
494
|
+
* ```tsx
|
|
495
|
+
* function StakeComponent() {
|
|
496
|
+
* const stake = useMemo(() => sdk.btc.stake({ ... }), []);
|
|
497
|
+
* useRegisterAction('stake', stake);
|
|
498
|
+
*
|
|
499
|
+
* return <button onClick={() => stake.prepare({ ... })}>Stake</button>;
|
|
500
|
+
* }
|
|
501
|
+
* ```
|
|
502
|
+
*/
|
|
503
|
+
declare function useRegisterAction(name: string, action: MonitorableAction | null, category?: string): void;
|
|
504
|
+
|
|
505
|
+
type TabId = 'events' | 'reducer' | 'state' | 'network';
|
|
506
|
+
interface DevToolsPanelProps {
|
|
507
|
+
/** SDK events to display */
|
|
508
|
+
events: DevToolsEvent[];
|
|
509
|
+
/** Clear SDK events callback */
|
|
510
|
+
onClearEvents: () => void;
|
|
511
|
+
/** Reducer action logs */
|
|
512
|
+
reducerLogs?: ReducerLogEntry[];
|
|
513
|
+
/** Clear reducer logs callback */
|
|
514
|
+
onClearReducerLogs?: () => void;
|
|
515
|
+
/** Current state for inspection */
|
|
516
|
+
state?: Record<string, unknown>;
|
|
517
|
+
/** Network log entries */
|
|
518
|
+
networkLog?: NetworkLogEntry[];
|
|
519
|
+
/** Clear network log callback */
|
|
520
|
+
onClearNetworkLog?: () => void;
|
|
521
|
+
/** Initial tab to show */
|
|
522
|
+
initialTab?: TabId;
|
|
523
|
+
/** Whether to show minimized by default */
|
|
524
|
+
defaultMinimized?: boolean;
|
|
525
|
+
/** Custom class name */
|
|
526
|
+
className?: string;
|
|
527
|
+
/** Optional title */
|
|
528
|
+
title?: string;
|
|
529
|
+
/** Callback when minimize button is clicked (for external control) */
|
|
530
|
+
onMinimize?: () => void;
|
|
531
|
+
}
|
|
532
|
+
/**
|
|
533
|
+
* DevTools Panel Component
|
|
534
|
+
*
|
|
535
|
+
* Main container for all DevTools functionality with tabbed navigation.
|
|
536
|
+
*/
|
|
537
|
+
declare function DevToolsPanel({ events, onClearEvents, reducerLogs, onClearReducerLogs, state, networkLog, onClearNetworkLog, initialTab, defaultMinimized, className, title, onMinimize, }: DevToolsPanelProps): react_jsx_runtime.JSX.Element;
|
|
538
|
+
|
|
539
|
+
interface EventLogProps {
|
|
540
|
+
/** Events to display */
|
|
541
|
+
events: DevToolsEvent[];
|
|
542
|
+
/** Callback to clear events */
|
|
543
|
+
onClear: () => void;
|
|
544
|
+
/** Optional title override */
|
|
545
|
+
title?: string;
|
|
546
|
+
/** Whether to show the info banner */
|
|
547
|
+
showInfoBanner?: boolean;
|
|
548
|
+
/** Custom class name for the container */
|
|
549
|
+
className?: string;
|
|
550
|
+
}
|
|
551
|
+
/**
|
|
552
|
+
* Event Log Component
|
|
553
|
+
*
|
|
554
|
+
* Console-style log showing SDK events with timestamps and color coding.
|
|
555
|
+
*/
|
|
556
|
+
declare function EventLog({ events, onClear, title, showInfoBanner, className, }: EventLogProps): react_jsx_runtime.JSX.Element;
|
|
557
|
+
|
|
558
|
+
interface NetworkLogProps {
|
|
559
|
+
/** Network log entries */
|
|
560
|
+
entries: NetworkLogEntry[];
|
|
561
|
+
/** Clear network log callback */
|
|
562
|
+
onClear: () => void;
|
|
563
|
+
/** Maximum height for scrolling */
|
|
564
|
+
maxHeight?: string;
|
|
565
|
+
}
|
|
566
|
+
declare function NetworkLog({ entries, onClear, maxHeight }: NetworkLogProps): react_jsx_runtime.JSX.Element;
|
|
567
|
+
|
|
568
|
+
interface ReducerLogProps {
|
|
569
|
+
/** Log entries to display */
|
|
570
|
+
logs: ReducerLogEntry[];
|
|
571
|
+
/** Callback to clear logs */
|
|
572
|
+
onClear: () => void;
|
|
573
|
+
/** Custom class name */
|
|
574
|
+
className?: string;
|
|
575
|
+
}
|
|
576
|
+
/**
|
|
577
|
+
* Reducer Log Component
|
|
578
|
+
*
|
|
579
|
+
* Displays reducer actions in a time-ordered list with expandable details.
|
|
580
|
+
*/
|
|
581
|
+
declare function ReducerLog({ logs, onClear, className }: ReducerLogProps): react_jsx_runtime.JSX.Element;
|
|
582
|
+
|
|
583
|
+
/**
|
|
584
|
+
* StateInspector - Debug panel for inspecting state objects
|
|
585
|
+
*
|
|
586
|
+
* Displays state in an expandable JSON tree with syntax highlighting.
|
|
587
|
+
* Supports copy-to-clipboard and collapsible sections.
|
|
588
|
+
*
|
|
589
|
+
* @module sdk-devtools/components/StateInspector
|
|
590
|
+
*/
|
|
591
|
+
interface StateInspectorProps {
|
|
592
|
+
/** State object to inspect */
|
|
593
|
+
state: Record<string, unknown>;
|
|
594
|
+
/** Optional title */
|
|
595
|
+
title?: string;
|
|
596
|
+
/** Initial expansion depth (default: 2) */
|
|
597
|
+
defaultExpandDepth?: number;
|
|
598
|
+
/** Custom class name */
|
|
599
|
+
className?: string;
|
|
600
|
+
}
|
|
601
|
+
/**
|
|
602
|
+
* State Inspector Component
|
|
603
|
+
*
|
|
604
|
+
* Renders a collapsible JSON tree viewer with syntax highlighting.
|
|
605
|
+
*/
|
|
606
|
+
declare function StateInspector({ state, title, defaultExpandDepth, className, }: StateInspectorProps): react_jsx_runtime.JSX.Element;
|
|
607
|
+
|
|
608
|
+
/**
|
|
609
|
+
* StatusBadge - Displays current flow status with color coding
|
|
610
|
+
*
|
|
611
|
+
* Shows the action status in a pill/badge format with appropriate colors.
|
|
612
|
+
*
|
|
613
|
+
* @module sdk-devtools/components/StatusBadge
|
|
614
|
+
*/
|
|
615
|
+
interface StatusBadgeProps {
|
|
616
|
+
/** Status string to display */
|
|
617
|
+
status?: string | unknown;
|
|
618
|
+
/** Custom class name */
|
|
619
|
+
className?: string;
|
|
620
|
+
}
|
|
621
|
+
/**
|
|
622
|
+
* Status Badge Component
|
|
623
|
+
*
|
|
624
|
+
* Displays action status with color coding based on status type.
|
|
625
|
+
*/
|
|
626
|
+
declare function StatusBadge({ status, className }: StatusBadgeProps): react_jsx_runtime.JSX.Element;
|
|
627
|
+
|
|
628
|
+
/**
|
|
629
|
+
* Simple step definition (minimal required fields)
|
|
630
|
+
*/
|
|
631
|
+
interface SimpleStep {
|
|
632
|
+
id: string;
|
|
633
|
+
label: string;
|
|
634
|
+
}
|
|
635
|
+
interface StepIndicatorProps {
|
|
636
|
+
/** Steps to display - can be simple { id, label } or full FlowStep */
|
|
637
|
+
steps: SimpleStep[] | FlowStep[];
|
|
638
|
+
/** Current step index (0-based) */
|
|
639
|
+
currentStep: number;
|
|
640
|
+
/** Custom class name */
|
|
641
|
+
className?: string;
|
|
642
|
+
}
|
|
643
|
+
/**
|
|
644
|
+
* Step Indicator Component
|
|
645
|
+
*
|
|
646
|
+
* Horizontal progress indicator showing completed, current, and upcoming steps.
|
|
647
|
+
* Uses inline styles for sizing to avoid Tailwind v4 --spacing variable issues.
|
|
648
|
+
* Steps have equal widths to align with the progress bar above.
|
|
649
|
+
*/
|
|
650
|
+
declare function StepIndicator({ steps, currentStep, className, }: StepIndicatorProps): react_jsx_runtime.JSX.Element;
|
|
651
|
+
/**
|
|
652
|
+
* Helper to convert simple step configs to FlowStep format
|
|
653
|
+
*/
|
|
654
|
+
declare function createSteps(configs: Array<{
|
|
655
|
+
id: string;
|
|
656
|
+
label: string;
|
|
657
|
+
description?: string;
|
|
658
|
+
}>, currentStep: number): FlowStep[];
|
|
659
|
+
|
|
660
|
+
/**
|
|
661
|
+
* useDevTools - React hook for integrating DevTools with SDK actions
|
|
662
|
+
*
|
|
663
|
+
* This is the main hook that developers will use to connect DevTools
|
|
664
|
+
* to their SDK usage. It provides:
|
|
665
|
+
* - Automatic event collection
|
|
666
|
+
* - Action registration
|
|
667
|
+
* - State for DevTools components
|
|
668
|
+
*
|
|
669
|
+
* @module sdk-devtools/hooks/useDevTools
|
|
670
|
+
*/
|
|
671
|
+
|
|
672
|
+
interface UseDevToolsReturn {
|
|
673
|
+
/** All collected events */
|
|
674
|
+
events: DevToolsEvent[];
|
|
675
|
+
/** All registered actions */
|
|
676
|
+
actions: Map<string, RegisteredAction>;
|
|
677
|
+
/** Current state summary */
|
|
678
|
+
stateSummary: Record<string, {
|
|
679
|
+
status: string;
|
|
680
|
+
isLoading: boolean;
|
|
681
|
+
hasError: boolean;
|
|
682
|
+
}>;
|
|
683
|
+
/** Register an action for monitoring */
|
|
684
|
+
registerAction: (name: string, action: MonitorableAction, options?: {
|
|
685
|
+
category?: string;
|
|
686
|
+
}) => () => void;
|
|
687
|
+
/** Unregister an action */
|
|
688
|
+
unregisterAction: (name: string) => void;
|
|
689
|
+
/** Clear all events */
|
|
690
|
+
clearEvents: () => void;
|
|
691
|
+
/** Clear all actions */
|
|
692
|
+
clearActions: () => void;
|
|
693
|
+
/** The underlying bridge instance */
|
|
694
|
+
bridge: DevToolsBridge;
|
|
695
|
+
}
|
|
696
|
+
/**
|
|
697
|
+
* React hook for DevTools integration
|
|
698
|
+
*
|
|
699
|
+
* @example Basic usage
|
|
700
|
+
* ```tsx
|
|
701
|
+
* function MyComponent() {
|
|
702
|
+
* const { events, registerAction, clearEvents } = useDevTools();
|
|
703
|
+
*
|
|
704
|
+
* useEffect(() => {
|
|
705
|
+
* const stake = sdk.btc.stake({ destChain: Chain.ETHEREUM, assetOut: AssetId.LBTC });
|
|
706
|
+
* const unregister = registerAction('stake', stake);
|
|
707
|
+
*
|
|
708
|
+
* return unregister;
|
|
709
|
+
* }, []);
|
|
710
|
+
*
|
|
711
|
+
* return (
|
|
712
|
+
* <DevToolsPanel
|
|
713
|
+
* events={events}
|
|
714
|
+
* onClearEvents={clearEvents}
|
|
715
|
+
* />
|
|
716
|
+
* );
|
|
717
|
+
* }
|
|
718
|
+
* ```
|
|
719
|
+
*
|
|
720
|
+
* @example With useAction helper
|
|
721
|
+
* ```tsx
|
|
722
|
+
* function MyComponent() {
|
|
723
|
+
* const { registerAction } = useDevTools();
|
|
724
|
+
*
|
|
725
|
+
* const stake = useAction(() => {
|
|
726
|
+
* const action = sdk.btc.stake({ ... });
|
|
727
|
+
* registerAction('stake', action);
|
|
728
|
+
* return action;
|
|
729
|
+
* }, []);
|
|
730
|
+
*
|
|
731
|
+
* // stake is automatically monitored
|
|
732
|
+
* }
|
|
733
|
+
* ```
|
|
734
|
+
*/
|
|
735
|
+
declare function useDevTools(config?: DevToolsConfig): UseDevToolsReturn;
|
|
736
|
+
/**
|
|
737
|
+
* Hook that creates an action and automatically registers it with DevTools
|
|
738
|
+
*
|
|
739
|
+
* @example
|
|
740
|
+
* ```tsx
|
|
741
|
+
* const stake = useMonitoredAction(
|
|
742
|
+
* 'btc-stake',
|
|
743
|
+
* () => sdk.btc.stake({ destChain: Chain.ETHEREUM, assetOut: AssetId.LBTC }),
|
|
744
|
+
* [sdk],
|
|
745
|
+
* );
|
|
746
|
+
* ```
|
|
747
|
+
*/
|
|
748
|
+
declare function useMonitoredAction<T extends MonitorableAction>(name: string, createAction: () => T, deps: React.DependencyList): T | null;
|
|
749
|
+
/**
|
|
750
|
+
* Hook that subscribes to events from a specific action
|
|
751
|
+
*
|
|
752
|
+
* @example
|
|
753
|
+
* ```tsx
|
|
754
|
+
* const { events, status, isLoading, error } = useActionEvents(stakeAction);
|
|
755
|
+
* ```
|
|
756
|
+
*/
|
|
757
|
+
declare function useActionEvents(action: MonitorableAction | null): {
|
|
758
|
+
events: DevToolsEvent[];
|
|
759
|
+
status: string;
|
|
760
|
+
isLoading: boolean;
|
|
761
|
+
error: Error | null;
|
|
762
|
+
isFailed: boolean;
|
|
763
|
+
clearEvents: () => void;
|
|
764
|
+
};
|
|
765
|
+
|
|
766
|
+
/**
|
|
767
|
+
* useMockWallet - Simulated wallet for testing SDK flows
|
|
768
|
+
*
|
|
769
|
+
* Provides mock addresses for exploring SDK without connecting a real wallet.
|
|
770
|
+
*
|
|
771
|
+
* IMPORTANT LIMITATIONS:
|
|
772
|
+
* The mock wallet provides valid addresses for UI exploration and auto-filling
|
|
773
|
+
* recipient fields. However, it CANNOT perform actual wallet operations:
|
|
774
|
+
* - EIP-712 signature signing (fee authorization)
|
|
775
|
+
* - Transaction signing
|
|
776
|
+
* - Message signing
|
|
777
|
+
*
|
|
778
|
+
* For full flow testing, connect a real wallet.
|
|
779
|
+
*
|
|
780
|
+
* @module sdk-devtools/hooks/useMockWallet
|
|
781
|
+
*/
|
|
782
|
+
|
|
783
|
+
/**
|
|
784
|
+
* Deterministic mock addresses for consistent testing.
|
|
785
|
+
* Uses well-known addresses that are valid for each chain type.
|
|
786
|
+
*/
|
|
787
|
+
declare const MOCK_ADDRESSES: MockAddresses;
|
|
788
|
+
/**
|
|
789
|
+
* Mock wallet limitations - clearly document what it can/cannot do
|
|
790
|
+
*/
|
|
791
|
+
declare const MOCK_WALLET_LIMITATIONS: {
|
|
792
|
+
/** Cannot sign transactions */
|
|
793
|
+
cannotSign: boolean;
|
|
794
|
+
/** Steps that work with mock wallet */
|
|
795
|
+
supportedSteps: readonly ["Create", "Prepare"];
|
|
796
|
+
/** Steps that require real wallet */
|
|
797
|
+
unsupportedSteps: readonly ["Authorize", "Sign", "Execute"];
|
|
798
|
+
/** User-friendly message */
|
|
799
|
+
message: string;
|
|
800
|
+
/** Short message for badges */
|
|
801
|
+
shortMessage: string;
|
|
802
|
+
};
|
|
803
|
+
/**
|
|
804
|
+
* Hook for managing mock wallet state
|
|
805
|
+
*
|
|
806
|
+
* Provides a mock wallet that auto-fills addresses but cannot sign transactions.
|
|
807
|
+
* State is persisted in localStorage.
|
|
808
|
+
*
|
|
809
|
+
* @example
|
|
810
|
+
* ```tsx
|
|
811
|
+
* const mockWallet = useMockWallet();
|
|
812
|
+
*
|
|
813
|
+
* if (!connectedWallet && !mockWallet.isEnabled) {
|
|
814
|
+
* return <button onClick={mockWallet.enable}>Use Mock Wallet</button>;
|
|
815
|
+
* }
|
|
816
|
+
*
|
|
817
|
+
* const address = connectedWallet?.address ?? mockWallet.address;
|
|
818
|
+
* ```
|
|
819
|
+
*/
|
|
820
|
+
declare function useMockWallet(): MockWalletState;
|
|
821
|
+
/**
|
|
822
|
+
* Get mock address for a chain type
|
|
823
|
+
*/
|
|
824
|
+
declare function getMockAddress(chainType: keyof MockAddresses): string;
|
|
825
|
+
/**
|
|
826
|
+
* Check if a step requires a real wallet
|
|
827
|
+
*/
|
|
828
|
+
declare function requiresRealWallet(stepLabel: string): boolean;
|
|
829
|
+
|
|
830
|
+
export { type ApiRequestEvent, type ApiResponseEvent, DEFAULT_DEVTOOLS_CONFIG, DevToolsBridge, type DevToolsConfig, type DevToolsEvent, type DevToolsEventCallback, DevToolsPanel, type DevToolsPanelProps, type DevToolsPosition, DevToolsProvider, type DevToolsProviderProps, type DevToolsStateCallback, type DevToolsTheme, type DevToolsWarning, EventLog, type EventLogProps, type FlowStep, type HttpMethod, MOCK_ADDRESSES, MOCK_WALLET_LIMITATIONS, type MockAddresses, type MockWalletState, type MonitorableAction, NetworkLog, type NetworkLogEntry, ReducerLog, type ReducerLogEntry, type ReducerLogProps, type RegisteredAction, StateInspector, type StateInspectorProps, StatusBadge, type StatusBadgeProps, StepIndicator, type StepIndicatorProps, type UseDevToolsReturn, type WarningSeverity, createSteps, getDevToolsBridge, getMockAddress, requiresRealWallet, resetDevToolsBridge, useActionEvents, useDevTools, useDevToolsContext, useMockWallet, useMonitoredAction, useRegisterAction };
|