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

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 Lombard Finance
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,348 @@
+# @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      │                    │
+│   │  .chain.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.chain.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.chain.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