@ffaerber/swarm-connect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Felix Faerber
+
+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,147 @@
+# swarm-connect
+
+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.
+
+## Features
+
+- 🐝 **Bee node detection** — checks a Bee node's `/health` endpoint and surfaces its version.
+- 🎟️ **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.
+
+## Installation
+
+```bash
+npm install @ffaerber/swarm-connect
+```
+
+### Peer dependencies
+
+This package expects the following to be installed in your app:
+
+```bash
+npm install react react-dom wagmi viem @tanstack/react-query
+```
+
+| Package | Version |
+| --- | --- |
+| `react` | `>=18` |
+| `react-dom` | `>=18` |
+| `wagmi` | `>=2` |
+| `viem` | `>=2` |
+| `@tanstack/react-query` | `>=5` |
+
+## Quick start
+
+Wrap your app in `SwarmConnectProvider` and drop in the button:
+
+```tsx
+import { SwarmConnectProvider, SwarmConnectButton } from '@ffaerber/swarm-connect'
+
+export function App() {
+  return (
+    <SwarmConnectProvider>
+      <SwarmConnectButton beeApiUrl="http://localhost:1633" />
+    </SwarmConnectProvider>
+  )
+}
+```
+
+`SwarmConnectProvider` sets up wagmi (Gnosis chain + injected connector) and a React Query client for you. If your app already has its own `WagmiProvider` and `QueryClientProvider`, you can skip the provider and use `SwarmConnectButton` directly.
+
+## Components
+
+### `<SwarmConnectProvider>`
+
+Provides the wagmi and React Query context. Configured for the Gnosis chain with an injected connector.
+
+| Prop | Type | Description |
+| --- | --- | --- |
+| `children` | `ReactNode` | Your app. |
+| `config` | `SwarmConnectConfig` | Optional configuration. |
+
+### `<SwarmConnectButton>`
+
+The connect button. Opens a two-tab modal (**Swarm** for the Bee node + postage stamp, **Wallet** for connecting your wallet).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `beeApiUrl` | `string` | `http://localhost:1633` | Base URL of the Bee node API. |
+| `label` | `string` | auto | Overrides the button label. Defaults to `Connect to Swarm`, or the truncated address once fully connected. |
+
+### `<SwarmConnectModal>`
+
+The modal rendered by `SwarmConnectButton`. Exported for advanced use if you want to manage open/close state yourself.
+
+## Hooks
+
+### `useSwarmConnect(config?)`
+
+The top-level hook combining node, stamp, wallet, and network state.
+
+```tsx
+import { useSwarmConnect } from '@ffaerber/swarm-connect'
+
+function Status() {
+  const {
+    beeNode,          // { isRunning, isChecking, version?, error?, check() }
+    stamps,           // { stamps, isLoading, error?, fetchStamps(), selectedStampId?, selectStamp() }
+    isWalletConnected,
+    address,
+    isOnGnosis,
+    chainId,
+    isFullyConnected, // node running + stamp selected + wallet connected + on Gnosis
+  } = useSwarmConnect({ beeApiUrl: 'http://localhost:1633' })
+
+  return <span>{isFullyConnected ? 'Ready' : 'Not connected'}</span>
+}
+```
+
+### `useBeeNode(beeApiUrl?)`
+
+Checks a Bee node's health.
+
+```tsx
+const { isRunning, isChecking, version, error, check } = useBeeNode('http://localhost:1633')
+```
+
+### `usePostageStamps(beeApiUrl?)`
+
+Fetches and selects postage stamps.
+
+```tsx
+const { stamps, isLoading, error, fetchStamps, selectedStampId, selectStamp } =
+  usePostageStamps('http://localhost:1633')
+```
+
+## Configuration
+
+```ts
+interface SwarmConnectConfig {
+  beeApiUrl?: string // defaults to http://localhost:1633
+}
+```
+
+"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`).
+
+## Development
+
+```bash
+npm install
+npm run dev          # start Vite dev server
+npm run type-check   # type-check without emitting
+npm run build        # build the library + type declarations to dist/
+```
+
+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
+
+MIT

package/dist/components/SwarmConnectButton.d.ts

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

package/dist/components/SwarmConnectModal.d.ts

@@ -0,0 +1,11 @@
+import { BeeNodeStatus, PostageStampsState } from '../types';
+interface SwarmConnectModalProps {
+    onClose: () => void;
+    beeNode: BeeNodeStatus & {
+        check: () => void;
+    };
+    stamps: PostageStampsState;
+    beeApiUrl: string;
+}
+export declare function SwarmConnectModal({ onClose, beeNode, stamps, beeApiUrl }: SwarmConnectModalProps): import("react").JSX.Element;
+export {};

package/dist/components/tabs/SwarmTab.d.ts

@@ -0,0 +1,10 @@
+import { BeeNodeStatus, PostageStampsState } from '../../types';
+interface SwarmTabProps {
+    beeApiUrl: string;
+    beeNode: BeeNodeStatus & {
+        check: () => void;
+    };
+    stamps: PostageStampsState;
+}
+export declare function SwarmTab({ beeApiUrl, beeNode, stamps }: SwarmTabProps): import("react").JSX.Element;
+export {};

package/dist/components/tabs/WalletTab.d.ts

@@ -0,0 +1 @@
+export declare function WalletTab(): import("react").JSX.Element;

package/dist/constants.d.ts

@@ -0,0 +1,22 @@
+export declare const GNOSIS_CHAIN_ID = 100;
+export declare const DEFAULT_BEE_API_URL = "http://localhost:1633";
+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";
+    };
+};

package/dist/context/SwarmConnectProvider.d.ts

@@ -0,0 +1,8 @@
+import { default as React } from 'react';
+import { SwarmConnectConfig } from '../types';
+interface SwarmConnectProviderProps {
+    children: React.ReactNode;
+    config?: SwarmConnectConfig;
+}
+export declare function SwarmConnectProvider({ children }: SwarmConnectProviderProps): React.JSX.Element;
+export {};

package/dist/hooks/useBeeNode.d.ts

@@ -0,0 +1,7 @@
+export declare function useBeeNode(beeApiUrl?: string): {
+    check: () => Promise<void>;
+    isRunning: boolean;
+    isChecking: boolean;
+    version?: string;
+    error?: string;
+};

package/dist/hooks/usePostageStamps.d.ts

@@ -0,0 +1,2 @@
+import { PostageStampsState } from '../types';
+export declare function usePostageStamps(beeApiUrl?: string): PostageStampsState;

package/dist/hooks/useSwarmConnect.d.ts

@@ -0,0 +1,2 @@
+import { SwarmConnectConfig, SwarmConnectState } from '../types';
+export declare function useSwarmConnect(config?: SwarmConnectConfig): SwarmConnectState;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export { SwarmConnectButton } from './components/SwarmConnectButton';
+export { SwarmConnectModal } from './components/SwarmConnectModal';
+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';