@ffaerber/swarm-connect 0.3.0 → 0.5.0

package/README.md

@@ -1,16 +1,25 @@
 # 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.
+- 🎛️ **Per-dApp requirements** (`requirements: { xdai, xbzz, postageStamp }`) — each dApp declares what "connected" means for it. Disabled requirements drop their step from the modal and from `isFullyConnected`. E.g. a dApp that manages stamps itself uses `{ xdai: true, xbzz: false, postageStamp: false }`.
+- 💸 **Node-wallet funding** (`xbzz: true`) — for dApps that buy stamps themselves: shows the Bee node's own wallet (`/wallet`) and lets the user top it up with xDAI + xBZZ from their connected wallet (one-time setup). The dApp then buys stamps programmatically via `stamps.createStamp()` — the modal itself never purchases.
+- ✅ **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 +74,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 — wallet → network (Gnosis) → xDAI balance → Bee node → node wallet → postage stamp — where each step unlocks only once the previous one is satisfied. Which steps appear depends on `requirements`: wallet, network, and Bee node are always present; the xDAI balance, node-wallet funding, and stamp-selection steps are included only when their requirement is enabled, and the numbering adapts. 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. |
+| `requirements` | `SwarmConnectRequirements` | `{ xdai: true, xbzz: false, postageStamp: true }` | Which requirements this dApp needs; disabled ones drop their step. See [Requirements](#requirements). |
 | `label` | `string` | auto | Overrides the button label. Defaults to `Connect to Swarm`, or the truncated address once fully connected. |
 
 ### `<SwarmConnectModal>`
@@ -80,7 +90,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 +98,22 @@ 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
+    requirements,     // resolved { xdai, xbzz, postageStamp } booleans
     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 + node + every enabled requirement
+  } = useSwarmConnect({
+    beeApiUrl: 'http://localhost:1633',
+    // this dApp needs user gas, but manages stamps itself:
+    requirements: { xdai: true, xbzz: false, postageStamp: false },
+  })
 
   return <span>{isFullyConnected ? 'Ready' : 'Not connected'}</span>
 }
@@ -112,39 +129,93 @@ const { isRunning, isChecking, version, error, check } = useBeeNode('http://loca
 
 ### `usePostageStamps(beeApiUrl?)`
 
-Fetches and selects postage stamps.
+Fetches, selects, and (for dApps that buy stamps themselves) creates 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
+  requirements?: SwarmConnectRequirements // which steps this dApp needs; see below
 }
 ```
 
-`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.
+
+### Requirements
 
-"Fully connected" requires all of the following:
+Every dApp needs a connected wallet, the Gnosis chain, and a reachable Bee node — those steps are always present. The rest is per-dApp via `requirements`; a disabled requirement drops its step from the modal and is ignored by `isFullyConnected`:
 
-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`).
+```ts
+interface SwarmConnectRequirements {
+  xdai?: boolean         // default true  — user wallet must hold xDAI for gas
+  xbzz?: boolean         // default false — node wallet funded (xDAI + xBZZ) so the dApp can buy stamps
+  postageStamp?: boolean // default true  — user must select a postage stamp in the modal
+}
+```
+
+- **`xdai`** — adds the *Balance* step: shows the connected wallet's native xDAI on Gnosis and links a faucet while it's empty. Disable for read-only dApps that never transact from the user's wallet.
+- **`xbzz`** — adds the *Node wallet* step: shows the Bee node's own xDAI/xBZZ balances (`GET /wallet`) 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). Enable when your dApp buys stamps itself — purchasing is your dApp's job via `stamps.createStamp({ amount, depth, label })` (`POST /stamps/{amount}/{depth}`); the modal never buys.
+- **`postageStamp`** — adds the *Postage stamp* step where the user picks an existing stamp. Disable when the dApp manages stamps itself (e.g. it creates and tracks its own batches).
+
+Example — a dApp that needs user gas but manages stamps itself:
+
+```tsx
+<SwarmConnectButton requirements={{ xdai: true, xbzz: false, postageStamp: false }} />
+```
+
+"Fully connected" requires all of the following (skipping disabled requirements):
+
+1. A connected wallet.
+2. The wallet on the Gnosis chain (chain ID `100`).
+3. *(`xdai`)* A non-zero xDAI balance on that wallet.
+4. A reachable Bee node (`/health` responds OK).
+5. *(`xbzz`)* The node's wallet funded with xDAI + xBZZ.
+6. *(`postageStamp`)* 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 playground in [`example/`](./example) for testing sign-in end to end. It shows **four connection scenarios side by side** — classic stamp selection, dApp-managed stamps (`postageStamp: false`), dApp-buys-stamps with node funding (`xbzz: true`), and a minimal node-only flow — each with its own `useSwarmConnect` instance and modal, so you can see how the gated steps adapt to `requirements`. Once a scenario is fully connected its card shows the live state: wallet address, chain, xDAI balance, Bee node URL + version, the node's overlay address, node-wallet balances, and the selected postage stamp (as applicable). Point it at a running Bee node (defaults to `http://localhost:1633`, editable in each 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, requirements, label }: SwarmConnectButtonProps): import("react").JSX.Element;
 export {};

package/dist/components/SwarmConnectModal.d.ts

@@ -1,12 +1,17 @@
-import { BeeNodeStatus, PostageStampsState } from '../types';
+import { BeeNodeStatus, NodeWalletState, PostageStampsState, SwarmConnectRequirements } from '../types';
 interface SwarmConnectModalProps {
     onClose: () => void;
     beeNode: BeeNodeStatus & {
         check: () => void;
+        disconnect: () => void;
     };
     stamps: PostageStampsState;
     beeApiUrl: string;
     setBeeApiUrl: (url: string) => void;
+    /** Per-dApp requirements; disabled ones drop their step. See SwarmConnectRequirements. */
+    requirements?: SwarmConnectRequirements;
+    /** 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, requirements, 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,34 @@
+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 }: {
+    stamps: PostageStampsState;
+    locked: boolean;
+    lockedHint: string;
+}): import("react").JSX.Element;

package/dist/constants.d.ts

@@ -1,23 +1,16 @@
 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";
+/** Default per-dApp requirements; see SwarmConnectRequirements. */
+export declare const DEFAULT_REQUIREMENTS: {
+    readonly xdai: true;
+    readonly xbzz: false;
+    readonly postageStamp: true;
 };

package/dist/hooks/useBeeNode.d.ts

@@ -1,5 +1,6 @@
 export declare function useBeeNode(beeApiUrl?: string): {
     check: () => Promise<void>;
+    disconnect: () => void;
     isRunning: boolean;
     isChecking: boolean;
     version?: string;

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, SwarmConnectRequirements, BeeNodeStatus, PostageStamp, PostageStampsState, CreateStampOptions, BalanceState, NodeWalletState, } from './types';