@ffaerber/swarm-connect 0.3.0 → 0.4.0

package/README.md

@@ -1,16 +1,24 @@
 # swarm-connect
 
+[![npm version](https://img.shields.io/npm/v/@ffaerber/swarm-connect.svg)](https://www.npmjs.com/package/@ffaerber/swarm-connect)
+[![npm downloads](https://img.shields.io/npm/dm/@ffaerber/swarm-connect.svg)](https://www.npmjs.com/package/@ffaerber/swarm-connect)
+[![license](https://img.shields.io/npm/l/@ffaerber/swarm-connect.svg)](./LICENSE)
+
 A React connect-button and wizard for [Ethereum Swarm](https://www.ethswarm.org/) on the [Gnosis](https://www.gnosis.io/) chain. Drop in a single `<SwarmConnectButton />` and let users connect their wallet, verify a running Bee node, and pick a postage stamp — all from one modal.
 
+📦 **npm:** [`@ffaerber/swarm-connect`](https://www.npmjs.com/package/@ffaerber/swarm-connect)
+
 ## Features
 
+- 🪜 **Gated sequential flow** — steps unlock in order: wallet → Gnosis network → xDAI gas → Bee node → *(node wallet)* → postage stamp.
+- 🦊 **Wallet connect** — wallet connection via [wagmi](https://wagmi.sh/) connectors, pinned to the Gnosis chain (ID `100`), with an xDAI balance/gas check.
 - 🐝 **Bee node detection** — checks a Bee node's `/health` endpoint and surfaces its version.
-- 🔧 **Editable node URL** — users can change the Bee node hostname from the modal and reconnect (defaults to `http://localhost:1633`).
+- 🔧 **Editable node URL** — users can change the Bee node hostname from the modal and reconnect (defaults to `http://localhost:1633`); the chosen URL is persisted in `localStorage`.
 - 🎟️ **Postage stamp selection** — fetches available stamps from `/stamps` and lets the user pick one.
-- 🦊 **Wallet connect** — injected-wallet connection via [wagmi](https://wagmi.sh/), pinned to Gnosis chain (ID `100`).
-- ✅ **At-a-glance status** — the button shows status dots for node, stamp, wallet, and network.
-- 🧩 **Headless hooks** — use the `useSwarmConnect` / `useBeeNode` / `usePostageStamps` hooks to build your own UI.
-- 🎨 **Zero-dependency styling** — inline styles, no CSS imports required.
+- 💸 **Stamp-create mode** (`stampMode: 'create'`) — for dApps that buy stamps themselves: shows the Bee node's own wallet (`/wallet`), lets the user top it up with xDAI + xBZZ from their connected wallet (one-time setup), and buy stamps right from the modal (`POST /stamps`).
+- ✅ **At-a-glance status** — the button shows status dots for every gated step.
+- 🧩 **Headless hooks** — use the `useSwarmConnect` / `useBeeNode` / `usePostageStamps` / `useNodeWallet` hooks to build your own UI.
+- 🎨 **Self-contained dark theme** — scoped CSS variables and inline styles, no CSS import required.
 
 ## Installation
 
@@ -65,11 +73,12 @@ Provides the wagmi and React Query context. Configured for the Gnosis chain with
 
 ### `<SwarmConnectButton>`
 
-The connect button. Opens a two-tab modal (**Swarm** for the Bee node + postage stamp, **Wallet** for connecting your wallet).
+The connect button. Opens a dark-themed modal with sequential, gated steps — **1.** wallet, **2.** network (Gnosis), **3.** xDAI balance, **4.** Bee node, and **5.** postage stamp — where each step unlocks only once the previous one is satisfied. With `stampMode="create"` a **node wallet** step is inserted before the stamp step (making it six steps): it reads the Bee node's own wallet and, if it's empty, lets the user send it xDAI + xBZZ from their connected wallet so the node can buy postage stamps. The widget ships its own scoped styles (no CSS import required); the `Space Grotesk` / `Inter` / `JetBrains Mono` fonts are used when present and fall back to system fonts otherwise.
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `beeApiUrl` | `string` | `http://localhost:1633` | Base URL of the Bee node API. |
+| `stampMode` | `'select' \| 'create'` | `'select'` | `'select'`: only pick existing stamps. `'create'`: also fund the node wallet and buy stamps from the modal. |
 | `label` | `string` | auto | Overrides the button label. Defaults to `Connect to Swarm`, or the truncated address once fully connected. |
 
 ### `<SwarmConnectModal>`
@@ -80,7 +89,7 @@ The modal rendered by `SwarmConnectButton`. Exported for advanced use if you wan
 
 ### `useSwarmConnect(config?)`
 
-The top-level hook combining node, stamp, wallet, and network state.
+The top-level hook combining wallet, network, balance, node, node-wallet, and stamp state.
 
 ```tsx
 import { useSwarmConnect } from '@ffaerber/swarm-connect'
@@ -88,15 +97,18 @@ import { useSwarmConnect } from '@ffaerber/swarm-connect'
 function Status() {
   const {
     beeNode,          // { isRunning, isChecking, version?, error?, check() }
-    stamps,           // { stamps, isLoading, error?, fetchStamps(), selectedStampId?, selectStamp() }
+    stamps,           // { stamps, isLoading, error?, fetchStamps(), selectedStampId?, selectStamp(), createStamp(), isCreating, createError? }
+    nodeWallet,       // { address?, xdai?, xbzz?, isLoading, error?, isFunded, refresh() } — the node's own wallet
     beeApiUrl,        // current Bee node URL
     setBeeApiUrl,     // change the Bee node URL at runtime, then re-check
+    stampMode,        // 'select' | 'create'
     isWalletConnected,
     address,
     isOnGnosis,
     chainId,
-    isFullyConnected, // node running + stamp selected + wallet connected + on Gnosis
-  } = useSwarmConnect({ beeApiUrl: 'http://localhost:1633' })
+    balance,          // { xdai?, isLoading, hasGas } — native xDAI on Gnosis
+    isFullyConnected, // wallet + Gnosis + xDAI gas + node (+ funded node wallet in create mode) + stamp
+  } = useSwarmConnect({ beeApiUrl: 'http://localhost:1633', stampMode: 'create' })
 
   return <span>{isFullyConnected ? 'Ready' : 'Not connected'}</span>
 }
@@ -112,39 +124,78 @@ const { isRunning, isChecking, version, error, check } = useBeeNode('http://loca
 
 ### `usePostageStamps(beeApiUrl?)`
 
-Fetches and selects postage stamps.
+Fetches, selects, and (in create-mode UIs) buys postage stamps.
 
 ```tsx
-const { stamps, isLoading, error, fetchStamps, selectedStampId, selectStamp } =
+const { stamps, isLoading, error, fetchStamps, selectedStampId, selectStamp,
+        createStamp, isCreating, createError } =
   usePostageStamps('http://localhost:1633')
+
+// Buy a batch via the node (cost = 2^depth × amount PLUR, paid by the node wallet):
+const batchID = await createStamp({ amount: '1000000000', depth: 20, label: 'my-app' })
 ```
 
+### `useNodeWallet(beeApiUrl?)`
+
+Reads the Bee node's **own** wallet — the one that pays for postage stamps — from `GET /wallet` and `GET /addresses`.
+
+```tsx
+const { address, xdai, xbzz, isLoading, error, isFunded, refresh } =
+  useNodeWallet('http://localhost:1633')
+```
+
+`isFunded` is true once the node wallet holds both xDAI (gas) and xBZZ (storage payment) — funding it is a **one-time setup**; returning users with a funded node skip the step automatically.
+
 ## Configuration
 
 ```ts
 interface SwarmConnectConfig {
-  beeApiUrl?: string // initial Bee node URL; defaults to http://localhost:1633
+  beeApiUrl?: string             // initial Bee node URL; defaults to http://localhost:1633
+  stampMode?: 'select' | 'create' // defaults to 'select'
 }
 ```
 
-`beeApiUrl` is only the **initial** value. Users can edit the node URL from the modal's Swarm tab (or programmatically via `setBeeApiUrl` from `useSwarmConnect`), which re-checks the node at the new address. This is useful when the Bee node runs on a non-default host or port.
+`beeApiUrl` is only the **initial** value. Users can edit the node URL from the modal's Bee node step (or programmatically via `setBeeApiUrl` from `useSwarmConnect`), which re-checks the node at the new address and persists the choice in `localStorage` so it survives sign-out / sign-in. This is useful when the Bee node runs on a non-default host or port.
+
+### Stamp modes
+
+Swarm splits responsibilities between two wallets: the **user's wallet** only needs xDAI for gas, while the **Bee node's wallet** needs xDAI *and* xBZZ because it is the one buying postage stamps on chain.
+
+- **`'select'`** (default) — the dApp only uses stamps the user already created. No xBZZ, no node funding, no on-chain spending from the modal.
+- **`'create'`** — the dApp can buy stamps. The modal gains a *node wallet* step that shows the node's xDAI/xBZZ balances and, while they're empty, offers a one-time top-up (a native xDAI transfer plus an ERC-20 xBZZ transfer to the node's address). The stamp step then also offers a *buy stamp* form (`POST /stamps/{amount}/{depth}`).
 
 "Fully connected" requires all of the following:
 
-1. A reachable Bee node (`/health` responds OK).
-2. A selected postage stamp.
-3. A connected wallet.
-4. The wallet on the Gnosis chain (chain ID `100`).
+1. A connected wallet.
+2. The wallet on the Gnosis chain (chain ID `100`).
+3. A non-zero xDAI balance on that wallet (gas for its own transactions).
+4. A reachable Bee node (`/health` responds OK).
+5. *(create mode only)* The node's wallet funded with xDAI + xBZZ.
+6. A selected postage stamp.
 
 ## Development
 
 ```bash
 npm install
-npm run dev          # start Vite dev server
+npm run dev          # start the demo app (example/) on the Vite dev server
 npm run type-check   # type-check without emitting
 npm run build        # build the library + type declarations to dist/
 ```
 
+### Demo app
+
+`npm run dev` serves a small playground in [`example/`](./example) for testing sign-in end to end. It renders the connect button and, once you're fully connected, shows the live state — wallet address, chain, xDAI balance, Bee node URL + version, the node's overlay (Bee) address, and the selected postage stamp. Point it at a running Bee node (defaults to `http://localhost:1633`, editable in the modal).
+
+**`ENOSPC: System limit for number of file watchers reached`?** Your machine's inotify watch limit is exhausted. Either:
+
+- **Quick fix** — run the dev server in polling mode: `npm run dev:poll`.
+- **Permanent fix** — raise the system limit:
+
+  ```bash
+  echo 'fs.inotify.max_user_watches=524288' | sudo tee /etc/sysctl.d/99-inotify.conf
+  sudo sysctl -p /etc/sysctl.d/99-inotify.conf
+  ```
+
 The library is built with Vite in library mode and ships ESM (`swarm-connect.js`), CommonJS (`swarm-connect.umd.cjs`), and TypeScript declarations. `react`, `react-dom`, `wagmi`, `viem`, and `@tanstack/react-query` are externalized.
 
 ## License

package/dist/components/SwarmConnectButton.d.ts

@@ -2,5 +2,5 @@ import { SwarmConnectConfig } from '../types';
 interface SwarmConnectButtonProps extends SwarmConnectConfig {
     label?: string;
 }
-export declare function SwarmConnectButton({ beeApiUrl, label }: SwarmConnectButtonProps): import("react").JSX.Element;
+export declare function SwarmConnectButton({ beeApiUrl, stampMode, label }: SwarmConnectButtonProps): import("react").JSX.Element;
 export {};

package/dist/components/SwarmConnectModal.d.ts

@@ -1,4 +1,4 @@
-import { BeeNodeStatus, PostageStampsState } from '../types';
+import { BeeNodeStatus, NodeWalletState, PostageStampsState, StampMode } from '../types';
 interface SwarmConnectModalProps {
     onClose: () => void;
     beeNode: BeeNodeStatus & {
@@ -7,6 +7,10 @@ interface SwarmConnectModalProps {
     stamps: PostageStampsState;
     beeApiUrl: string;
     setBeeApiUrl: (url: string) => void;
+    /** 'create' adds the node-wallet funding step and the buy-stamp form. */
+    stampMode?: StampMode;
+    /** Pass the instance from useSwarmConnect to share state; created internally otherwise. */
+    nodeWallet?: NodeWalletState;
 }
-export declare function SwarmConnectModal({ onClose, beeNode, stamps, beeApiUrl, setBeeApiUrl }: SwarmConnectModalProps): import("react").JSX.Element;
+export declare function SwarmConnectModal({ onClose, beeNode, stamps, beeApiUrl, setBeeApiUrl, stampMode, nodeWallet: nodeWalletProp, }: SwarmConnectModalProps): import("react").JSX.Element;
 export {};

package/dist/components/atoms.d.ts

@@ -0,0 +1,53 @@
+import { CSSProperties, ReactNode } from 'react';
+type Tone = 'ok' | 'bad' | 'warn';
+type StepState = 'locked' | 'active' | 'done';
+export declare function HexIcon({ size, stroke, glow, children }: {
+    size?: number;
+    stroke?: string;
+    glow?: boolean;
+    children: ReactNode;
+}): import("react").JSX.Element;
+export declare function Spinner({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+export declare function Badge({ children, tone }: {
+    children: ReactNode;
+    tone: Tone;
+}): import("react").JSX.Element;
+export declare function StatusRow({ tone, title, sub, children }: {
+    tone: Tone | 'flat';
+    title?: string;
+    sub?: string;
+    children?: ReactNode;
+}): import("react").JSX.Element;
+export declare function GhostBtn({ children, onClick, disabled }: {
+    children: ReactNode;
+    onClick?: () => void;
+    disabled?: boolean;
+}): import("react").JSX.Element;
+export declare function PrimaryBtn({ children, onClick, pending, block, style }: {
+    children: ReactNode;
+    onClick?: () => void;
+    pending?: boolean;
+    block?: boolean;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+export declare function LockedNotice({ children }: {
+    children: ReactNode;
+}): import("react").JSX.Element;
+/** Numbered, gated step header with a hex badge. */
+export declare function StepLabel({ step, state, children, hint }: {
+    step: number;
+    state: StepState;
+    children: ReactNode;
+    hint?: ReactNode;
+}): import("react").JSX.Element;
+/** The bee / hex brand mark. */
+export declare function BeeMark({ size }: {
+    size?: number;
+}): import("react").JSX.Element;
+/** Row of progress dots, one per gated step. */
+export declare function StepDots({ states }: {
+    states: boolean[];
+}): import("react").JSX.Element;
+export {};

package/dist/components/steps.d.ts

@@ -0,0 +1,35 @@
+import { BalanceState, BeeNodeStatus, NodeWalletState, PostageStampsState } from '../types';
+export declare function WalletStep({ isConnected, address }: {
+    isConnected: boolean;
+    address?: string;
+}): import("react").JSX.Element;
+export declare function NetworkStep({ locked, isOnGnosis, chainId }: {
+    locked: boolean;
+    isOnGnosis: boolean;
+    chainId?: number;
+}): import("react").JSX.Element;
+export declare function BalanceStep({ locked, balance }: {
+    locked: boolean;
+    balance: BalanceState;
+}): import("react").JSX.Element;
+export declare function NodeUrlInput({ value, disabled, onSubmit }: {
+    value: string;
+    disabled: boolean;
+    onSubmit: (url: string) => void;
+}): import("react").JSX.Element;
+export declare function BeeNodeStep({ node, beeApiUrl }: {
+    node: BeeNodeStatus & {
+        check: () => void;
+    };
+    beeApiUrl: string;
+}): import("react").JSX.Element;
+export declare function NodeWalletStep({ locked, nodeWallet }: {
+    locked: boolean;
+    nodeWallet: NodeWalletState;
+}): import("react").JSX.Element;
+export declare function StampStep({ stamps, locked, lockedHint, canCreate }: {
+    stamps: PostageStampsState;
+    locked: boolean;
+    lockedHint: string;
+    canCreate: boolean;
+}): import("react").JSX.Element;

package/dist/constants.d.ts

@@ -1,23 +1,13 @@
 export declare const GNOSIS_CHAIN_ID = 100;
 export declare const DEFAULT_BEE_API_URL = "http://localhost:1633";
 export declare const BEE_API_URL_STORAGE_KEY = "swarm-connect:bee-api-url";
-export declare const STYLES: {
-    readonly colors: {
-        readonly primary: "#1a56db";
-        readonly primaryHover: "#1e429f";
-        readonly success: "#0e9f6e";
-        readonly successLight: "#f0fdf4";
-        readonly error: "#f05252";
-        readonly errorLight: "#fff5f5";
-        readonly warning: "#ff8a4c";
-        readonly warningLight: "#fffbf5";
-        readonly border: "#e5e7eb";
-        readonly text: "#111827";
-        readonly muted: "#6b7280";
-        readonly bg: "#ffffff";
-        readonly overlay: "rgba(0,0,0,0.5)";
-        readonly stepInactive: "#d1d5db";
-        readonly stepActive: "#1a56db";
-        readonly stepDone: "#0e9f6e";
-    };
-};
+/** xBZZ (bridged BZZ) ERC-20 on Gnosis chain. */
+export declare const BZZ_TOKEN_ADDRESS: "0xdBF3Ea6F5beE45c02255B2c26a16F300502F68da";
+/** BZZ uses 16 decimals (1 xBZZ = 1e16 PLUR), unlike the usual 18. */
+export declare const BZZ_DECIMALS = 16;
+/** Suggested one-time top-up amounts for the Bee node's wallet. */
+export declare const DEFAULT_FUND_XDAI = "0.1";
+export declare const DEFAULT_FUND_XBZZ = "0.5";
+/** Suggested values for buying a postage stamp (cost = 2^depth × amount PLUR). */
+export declare const DEFAULT_STAMP_DEPTH = 20;
+export declare const DEFAULT_STAMP_AMOUNT = "1000000000";

package/dist/hooks/useNodeWallet.d.ts

@@ -0,0 +1,7 @@
+import { NodeWalletState } from '../types';
+/**
+ * Reads the Bee node's OWN wallet (GET /wallet) and Ethereum address
+ * (GET /addresses). This is the wallet that pays for postage stamps —
+ * separate from the user's browser wallet.
+ */
+export declare function useNodeWallet(beeApiUrl?: string): NodeWalletState;

package/dist/index.d.ts

@@ -4,4 +4,5 @@ export { SwarmConnectProvider } from './context/SwarmConnectProvider';
 export { useSwarmConnect } from './hooks/useSwarmConnect';
 export { useBeeNode } from './hooks/useBeeNode';
 export { usePostageStamps } from './hooks/usePostageStamps';
-export type { SwarmConnectConfig, SwarmConnectState, BeeNodeStatus, PostageStamp, PostageStampsState, } from './types';
+export { useNodeWallet } from './hooks/useNodeWallet';
+export type { SwarmConnectConfig, SwarmConnectState, StampMode, BeeNodeStatus, PostageStamp, PostageStampsState, CreateStampOptions, BalanceState, NodeWalletState, } from './types';