@lombard.finance/sdk-devtools 0.1.0-canary.2

package/README.md

@@ -0,0 +1,344 @@
+# @lombard.finance/sdk-devtools
+
+Developer tools for the Lombard SDK. Provides debugging, inspection, and testing utilities for developers integrating with the Lombard protocol.
+
+## How It Works
+
+The SDK DevTools automatically hooks into SDK actions to collect events and state:
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                                YOUR APP                                      │
+├─────────────────────────────────────────────────────────────────────────────┤
+│                                                                              │
+│   ┌─────────────────────┐        ┌─────────────────────┐                    │
+│   │    Lombard SDK      │        │     DevTools        │                    │
+│   │                     │        │                     │                    │
+│   │  const stake = sdk  │───────▶│  Automatically      │                    │
+│   │    .btc.stake(...)  │ events │  collects events,   │                    │
+│   │                     │        │  tracks status      │                    │
+│   └─────────────────────┘        └──────────┬──────────┘                    │
+│                                              │                               │
+│                                              ▼                               │
+│                               ┌─────────────────────────┐                   │
+│                               │    DevToolsPanel        │                   │
+│                               │    (Visual debugger)    │                   │
+│                               └─────────────────────────┘                   │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+## Installation
+
+```bash
+yarn add @lombard.finance/sdk-devtools
+# or
+npm install @lombard.finance/sdk-devtools
+```
+
+## Quick Start
+
+### 1. Wrap Your App with DevToolsProvider
+
+```tsx
+import { DevToolsProvider } from '@lombard.finance/sdk-devtools';
+
+function App() {
+  return (
+    <DevToolsProvider enabled={process.env.NODE_ENV !== 'production'}>
+      <MyApp />
+    </DevToolsProvider>
+  );
+}
+```
+
+### 2. Register SDK Actions
+
+```tsx
+import { useDevToolsContext } from '@lombard.finance/sdk-devtools';
+import { createLombardSDK, Chain, AssetId } from '@lombard.finance/sdk';
+
+function StakeComponent() {
+  const { registerAction } = useDevToolsContext();
+  const [stake, setStake] = useState(null);
+
+  // Create and register the action
+  useEffect(() => {
+    async function init() {
+      const sdk = await createLombardSDK({
+        env: 'testnet',
+        providers: { evm: () => window.ethereum },
+      });
+
+      const action = sdk.btc.stake({
+        destChain: Chain.ETHEREUM,
+        assetOut: AssetId.LBTC,
+      });
+
+      // Register with DevTools - events are now collected automatically!
+      const unregister = registerAction('btc-stake', action, {
+        category: 'btc',
+      });
+
+      setStake(action);
+
+      return unregister;
+    }
+
+    init();
+  }, [registerAction]);
+
+  // Use the action normally
+  async function handleStake() {
+    await stake.prepare({ amount: '0.001', recipient: '0x...' });
+    await stake.authorize();
+    const address = await stake.generateDepositAddress();
+    console.log('Deposit to:', address);
+  }
+
+  return <button onClick={handleStake}>Stake BTC</button>;
+}
+```
+
+### 3. Display DevTools Panel
+
+```tsx
+import { DevToolsPanel, useDevToolsContext } from '@lombard.finance/sdk-devtools';
+
+function DebugPanel() {
+  const { events, clearEvents, actions } = useDevToolsContext();
+
+  // Get state summary for all registered actions
+  const stateSummary = useMemo(() => {
+    const summary = {};
+    actions.forEach((reg, name) => {
+      summary[name] = {
+        status: reg.action.status,
+        isLoading: reg.action.isLoading,
+      };
+    });
+    return summary;
+  }, [actions]);
+
+  return (
+    <DevToolsPanel
+      events={events}
+      onClearEvents={clearEvents}
+      state={stateSummary}
+    />
+  );
+}
+```
+
+## Alternative: Without Provider
+
+For simpler setups or non-React apps, use the bridge directly:
+
+```tsx
+import { DevToolsBridge, DevToolsPanel } from '@lombard.finance/sdk-devtools';
+
+// Create bridge
+const bridge = new DevToolsBridge({ consoleLogging: true });
+
+// Register action
+const stake = sdk.btc.stake({ ... });
+const unregister = bridge.registerAction('stake', stake);
+
+// Get events for display
+const events = bridge.getEvents();
+
+// In React:
+function DebugView() {
+  const [events, setEvents] = useState([]);
+
+  useEffect(() => {
+    return bridge.onEvent(() => {
+      setEvents(bridge.getEvents());
+    });
+  }, []);
+
+  return (
+    <DevToolsPanel
+      events={events}
+      onClearEvents={() => bridge.clearEvents()}
+    />
+  );
+}
+```
+
+## Using Hook for Single Action
+
+For monitoring a single action with full state:
+
+```tsx
+import { useActionEvents } from '@lombard.finance/sdk-devtools';
+
+function StakeProgress({ action }) {
+  const { events, status, isLoading, error, isFailed } = useActionEvents(action);
+
+  return (
+    <div>
+      <StatusBadge status={status} />
+      {isLoading && <Spinner />}
+      {isFailed && <Error message={error.message} />}
+      <EventLog events={events} onClear={() => {}} />
+    </div>
+  );
+}
+```
+
+## Components
+
+### DevToolsPanel
+
+Full debug panel with tabs for events, actions, and state:
+
+```tsx
+<DevToolsPanel
+  events={events}
+  onClearEvents={clearEvents}
+  reducerLogs={logs}             // Optional: Redux-style action log
+  onClearReducerLogs={clearLogs} // Optional
+  state={{ status: 'ready' }}    // Optional: State to inspect
+  initialTab="events"            // Optional: 'events' | 'reducer' | 'state'
+  title="SDK Debug"              // Optional
+/>
+```
+
+### Individual Components
+
+```tsx
+import {
+  EventLog,
+  StateInspector,
+  StatusBadge,
+  StepIndicator,
+  createSteps,
+} from '@lombard.finance/sdk-devtools';
+
+// Status Badge
+<StatusBadge status="needs_fee_authorization" />
+
+// Step Indicator
+const steps = [
+  { id: 'create', label: 'Create' },
+  { id: 'prepare', label: 'Prepare' },
+  { id: 'authorize', label: 'Authorize' },
+  { id: 'execute', label: 'Execute' },
+];
+
+<StepIndicator
+  steps={createSteps(steps, currentStep)}
+  currentStep={currentStep}
+/>
+
+// Event Log (standalone)
+<EventLog events={events} onClear={clearEvents} />
+
+// State Inspector (JSON tree viewer)
+<StateInspector state={{ amount: '0.001' }} title="Transaction" />
+```
+
+## Mock Wallet
+
+Test flows without connecting a real wallet:
+
+```tsx
+import { useMockWallet, MOCK_ADDRESSES } from '@lombard.finance/sdk-devtools';
+
+function WalletSection() {
+  const mockWallet = useMockWallet();
+
+  return (
+    <div>
+      {!mockWallet.isEnabled ? (
+        <button onClick={mockWallet.enable}>Use Mock Wallet</button>
+      ) : (
+        <div>
+          <p>Mock Address: {mockWallet.address}</p>
+          <p>⚠️ Cannot sign transactions</p>
+          <button onClick={mockWallet.disable}>Disable Mock</button>
+        </div>
+      )}
+    </div>
+  );
+}
+
+// Available mock addresses
+console.log(MOCK_ADDRESSES.evm);      // 0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045
+console.log(MOCK_ADDRESSES.bitcoin);  // bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh
+console.log(MOCK_ADDRESSES.solana);   // DRpbCBMxVnDK7maPMxTm9dRYNLGhPEYALmJY9VvUdWTm
+```
+
+## SDK Events Collected
+
+The bridge automatically subscribes to these SDK events:
+
+| Event | Description |
+|-------|-------------|
+| `status-change` | Action status changed (e.g., `idle` → `needs_fee_authorization`) |
+| `loading` | Loading state changed |
+| `error` | An error occurred |
+| `completed` | Action completed successfully |
+| `failed` | Action failed |
+| `progress` | Progress update with step details |
+
+## API Reference
+
+### Provider
+
+| Export | Description |
+|--------|-------------|
+| `DevToolsProvider` | React context provider |
+| `useDevToolsContext` | Hook to access DevTools context |
+| `useRegisterAction` | Hook to register an action |
+
+### Bridge
+
+| Export | Description |
+|--------|-------------|
+| `DevToolsBridge` | Core bridge class |
+| `getDevToolsBridge` | Get global singleton bridge |
+| `resetDevToolsBridge` | Reset global bridge |
+
+### Hooks
+
+| Hook | Description |
+|------|-------------|
+| `useDevTools` | Full DevTools state and methods |
+| `useMonitoredAction` | Create and auto-register an action |
+| `useActionEvents` | Subscribe to events from a single action |
+| `useMockWallet` | Mock wallet for testing |
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `DevToolsPanel` | Full tabbed debug panel |
+| `EventLog` | SDK event stream |
+| `ReducerLog` | Redux-style action log |
+| `StateInspector` | JSON tree viewer |
+| `StatusBadge` | Status indicator |
+| `StepIndicator` | Progress steps |
+
+## Styling
+
+Components use Tailwind CSS classes. For best results, ensure Tailwind is configured in your project. Components support dark mode via `dark:` prefix classes.
+
+## Production
+
+DevTools is automatically disabled in production when using `DevToolsProvider`:
+
+```tsx
+<DevToolsProvider enabled={process.env.NODE_ENV !== 'production'}>
+```
+
+Or disable manually:
+
+```tsx
+<DevToolsProvider enabled={false}>
+```
+
+## License
+
+MIT