@maxtroost/use-websocket 1.0.0 → 1.1.0

package/README.md

@@ -1,238 +1,179 @@
-# @max-troost-io/use-websocket
+# @maxtroost/use-websocket
 
 A robust WebSocket connection management package for React applications with automatic reconnection, heartbeat monitoring, URI-based message routing, and React integration via TanStack Store.
 
 ## Installation
 
 ```bash
-npm install @max-troost-io/use-websocket
+npm install @maxtroost/use-websocket
 ```
 
-## 📚 Navigation
+**Peer dependencies:** React 18+, React DOM 18+
 
-### Internal Sections
+### Message Format
 
-- [Features & Purpose](#-features--purpose)
-- [Code Structure](#-code-structure)
-- [Data Flow & Architecture](#-data-flow--architecture)
-- [Key Behaviors](#-key-behaviors)
-- [Usage & Integration](#-usage--integration)
-- [Testing Strategy](#-testing-strategy)
-- [Troubleshooting & Debugging](#-troubleshooting--debugging)
-- [Dependencies](#-dependencies)
+All outgoing WebSocket messages share the same structure and are sent as JSON:
 
----
-
-## 🎯 Features & Purpose
+```json
+{
+  "method": "subscribe" | "unsubscribe" | "post",
+  "uri": "/path/to/endpoint",
+  "body": { ... }
+}
+```
 
-This package provides a comprehensive WebSocket solution for React applications that require real-time data streaming and request/response messaging over a single connection.
+| Field   | Required | Description                                                                 |
+| ------- | -------- | --------------------------------------------------------------------------- |
+| `method`| Optional | HTTP-like method: `subscribe`, `unsubscribe`, or `post` (default for custom messages) |
+| `uri`   | Yes      | Path for routing; the server uses this to dispatch to the correct handler  |
+| `body`  | Optional | Payload sent with the message                                               |
 
-### Problems Solved
+**Examples:**
 
-- **Duplicate connections**: Prevents multiple WebSocket connections to the same URL
-- **Stale connections**: Detects and recovers from silent connection failures via heartbeat
-- **Reconnection complexity**: Handles reconnection with exponential backoff and browser online/offline detection
-- **Subscription sharing**: Multiple components can share the same subscription via a unique key
-- **Auth-aware URLs**: WebSocket URLs are built from the current auth context (region, role, user)
+- **Subscribe** (streaming): `{ "method": "subscribe", "uri": "/notifications", "body": { "status": "active" } }`
+- **Unsubscribe**: `{ "method": "unsubscribe", "uri": "/notifications" }`
+- **Request/response** (e.g. validate, mark read): `{ "method": "post", "uri": "/voyages/modify/validate", "body": { ... } }`
 
-### Key Features
+You can add extra fields (e.g. auth headers) via `transformMessagePayload` in `WebsocketClient`.
 
-| Feature                      | Description                                                                                              |
-| ---------------------------- | -------------------------------------------------------------------------------------------------------- |
-| **Singleton Connection**     | One connection per URL shared across all hooks                                                           |
-| **Key-Based API Management** | Subscription and Message APIs identified by unique keys; components with the same key share the instance |
-| **Automatic Reconnection**   | Three-phase exponential backoff (4s → 30s → 90s)                                                         |
-| **Heartbeat Monitoring**     | Ping/pong every 40 seconds to detect stale connections                                                   |
-| **URI-Based Routing**        | Multiple subscriptions over a single connection                                                          |
-| **React Integration**        | TanStack Store for reactive data updates                                                                 |
-| **Online/Offline Detection** | Browser connectivity change handling                                                                     |
-| **Two API Types**            | **Subscription** for streaming data; **Message** for request/response commands                           |
+### Subscription vs Message
 
-### Target Users
+The package offers two patterns for different use cases:
 
-- **Developers** integrating real-time data (voyages, rotations, notifications) into React apps
-- **Applications** using `@mono-fleet/iam-provider` for region-based authentication
+| | **Subscription** (`useWebsocketSubscription`) | **Message** (`useWebsocketMessage`) |
+| --- | --- | --- |
+| **Pattern** | Streaming — subscribe once, receive ongoing updates | Request/response — send a message, get one reply (or none) |
+| **Use case** | Live data feeds (notifications, voyage list, real-time dashboards) | One-off commands (validate, modify, mark read) |
+| **URI** | Fixed per hook — one URI per subscription | Any URI — send to different endpoints per call |
+| **State** | TanStack Store — reactive `message`, `pendingSubscription`, `connected` | No store — returns a Promise or fire-and-forget |
+| **Lifecycle** | Auto-subscribes when connection opens; unsubscribes when last component unmounts | No subscription — just send when needed |
 
 ---
 
-## 🏗️ Code Structure
+## Basic Setup
 
-```
-packages/use-websocket/
-├── src/
-│   ├── index.ts                    # Public exports
-│   └── lib/
-│       ├── WebsocketHook.ts        # React hooks (useWebsocketSubscription, useWebsocketMessage, useWebsocketSubscriptionByKey)
-│       ├── WebsocketConnection.ts  # Connection lifecycle, reconnection, heartbeat
-│       ├── WebsocketSubscriptionApi.ts  # Streaming subscription per URI
-│       ├── WebsocketMessageApi.ts  # Request/response messaging (no subscription)
-│       ├── websocketStores.ts      # Global TanStack stores (connections, listeners)
-│       ├── websocketStores.helpers.ts  # findOrCreateWebsocketConnection, createWebsocketSubscriptionApi, etc.
-│       ├── types.ts                # Types, options, store shapes
-│       ├── constants.ts            # Timing, close codes, defaults
-│       ├── WebsocketConnection.helpers.ts  # Reconnection, ping, notifications
-│       └── WEBSOCKET_CONNECTION.md # Detailed architecture and flows
-├── README.md
-├── CHART.md                        # Mermaid flow diagrams
-└── package.json
-```
+1. Create a `WebsocketClient` and wrap your app with `WebsocketClientProvider`:
 
-### Component Hierarchy
-
-```mermaid
-graph TB
-    subgraph "React Layer"
-        Hook[useWebsocketSubscription / useWebsocketMessage]
-        ByKey[useWebsocketSubscriptionByKey]
-        Component[React Components]
-    end
-
-    subgraph "Connection Layer"
-        Connection[WebsocketConnection<br/>Singleton per URL]
-        SubApi[WebsocketSubscriptionApi<br/>One per key]
-        MsgApi[WebsocketMessageApi<br/>One per key]
-    end
-
-    subgraph "WebSocket API"
-        Socket[WebSocket]
-    end
-
-    Component -->|uses| Hook
-    Component -->|uses| ByKey
-    Hook -->|manages| Connection
-    Hook -->|creates| SubApi
-    Hook -->|creates| MsgApi
-    Connection -->|manages| Socket
-    Connection -->|routes messages to| SubApi
-    Connection -->|routes messages to| MsgApi
-    SubApi -->|TanStack Store| Component
-```
+```tsx
+import { WebsocketClient, WebsocketClientProvider } from "@maxtroost/use-websocket";
 
----
+const websocketClient = new WebsocketClient({
+  maxRetryAttempts: 20,
+  // Optional: customize heartbeat, timeouts, logging, etc.
+});
 
-## 🔄 Data Flow & Architecture
-
-### Choosing the Right Hook
-
-| Hook                            | Use Case                                                          |
-| ------------------------------- | ----------------------------------------------------------------- |
-| `useWebsocketSubscription`      | Streaming data (voyage list, notifications, live updates)         |
-| `useWebsocketMessage`           | One-off commands (validate, modify, mark read) — request/response |
-| `useWebsocketSubscriptionByKey` | Child component needs parent's subscription data                  |
-
-### Message Flow: Subscription
-
-```mermaid
-sequenceDiagram
-    participant Component
-    participant Hook as useWebsocketSubscription
-    participant Connection as WebsocketConnection
-    participant SubApi as WebsocketSubscriptionApi
-    participant Socket as WebSocket
-    participant Server
-
-    Component->>Hook: useWebsocketSubscription(options)
-    Hook->>Connection: findOrCreateWebsocketConnection(url)
-    Hook->>Connection: addListener(SubApi)
-    Connection->>Socket: new WebSocket(url)
-
-    Socket-->>Connection: open event
-    Connection->>SubApi: onOpen()
-    SubApi->>Socket: subscribe message
-    Socket->>Server: subscribe
-
-    Server-->>Socket: message (uri, body)
-    Socket-->>Connection: message event
-    Connection->>Connection: Route by URI
-    Connection->>SubApi: onMessage(body)
-    SubApi->>SubApi: Update TanStack Store
-    SubApi-->>Component: Store update triggers re-render
+function App() {
+  return (
+    <WebsocketClientProvider client={websocketClient}>
+      <YourApp />
+    </WebsocketClientProvider>
+  );
+}
 ```
 
-### Message Flow: Request/Response (useWebsocketMessage)
-
-```mermaid
-sequenceDiagram
-    participant Component
-    participant MsgApi as WebsocketMessageApi
-    participant Connection as WebsocketConnection
-    participant Socket as WebSocket
-    participant Server
-
-    Component->>MsgApi: sendMessage(uri, method, body?)
-    MsgApi->>Socket: Message with correlation ID
-    Socket->>Server: message
-
-    Server-->>Socket: response (same correlation)
-    Socket-->>Connection: message event
-    Connection->>MsgApi: deliverMessage(uri, data)
-    MsgApi->>MsgApi: resolve Promise
-    MsgApi-->>Component: await result
-```
+2. Use the hooks in your components:
 
----
+```tsx
+import { useWebsocketSubscription } from "@maxtroost/use-websocket";
+import { useStore } from "@tanstack/react-store";
 
-## ⚙️ Key Behaviors
+function LiveNotifications() {
+  const api = useWebsocketSubscription<Notification[]>({
+    key: "notifications",
+    url: "wss://api.example.com/ws",
+    uri: "/notifications",
+  });
 
-### Subscription Behavior
+  const notifications = useStore(api.store, (s) => s.message);
+  const loading = useStore(api.store, (s) => s.pendingSubscription);
+
+  if (loading) return <div>Connecting...</div>;
+  return (
+    <ul>
+      {notifications?.map((n) => (
+        <li key={n.id}>{n.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
 
-Subscriptions automatically subscribe when the WebSocket connection opens.
+---
 
-### Store Shape (WebsocketSubscriptionStore)
+## Features
 
-```typescript
-interface WebsocketSubscriptionStore<TData> {
-  message: TData | undefined; // Latest data from server
-  subscribed: boolean; // Subscription confirmed
-  pendingSubscription: boolean; // Subscribe sent, waiting for first response (for loading UI)
-  subscribedAt: number | undefined;
-  receivedAt: number | undefined;
-  connected: boolean; // WebSocket open
-  messageError: WebsocketTransportError | undefined;
-  serverError: WebsocketServerError<unknown> | undefined;
-}
-```
+- **Automatic reconnection** — Exponential backoff (4s → 30s → 90s) with configurable max attempts
+- **Heartbeat monitoring** — Ping/pong to detect stale connections
+- **URI-based routing** — Messages routed by URI; one connection per URL shared across subscriptions
+- **TanStack Store integration** — Reactive state for subscriptions; components re-render on updates
+- **Two patterns** — `useWebsocketSubscription` for streaming data, `useWebsocketMessage` for request/response
+- **Shared stores** — Child components access parent subscriptions via `useWebsocketSubscriptionByKey`
+- **Conditional subscriptions** — `enabled` option to pause when unauthenticated or feature-flagged off
+- **Lifecycle callbacks** — `onSubscribe`, `onMessage`, `onError`, `onClose` for logging and side effects
+- **Connection events** — `connectionEvent` callback for reconnection status, logging, or custom notifications
 
-### Reconnection Backoff
+---
 
-| Attempt Range | Wait Time  |
-| ------------- | ---------- |
-| 0–4 attempts  | 4 seconds  |
-| 5–9 attempts  | 30 seconds |
-| 10+ attempts  | 90 seconds |
+## API Reference
 
-User notifications are shown after 10 failed attempts. Reconnection stops after 20 attempts (~18 minutes); users can retry manually via the notification action.
+| Export | Description |
+| ------ | ----------- |
+| `useWebsocketSubscription` | Subscribe to a URI and receive streaming data via a reactive store |
+| `useWebsocketSubscriptionByKey` | Access the store of a subscription created elsewhere (by key) |
+| `useWebsocketMessage` | Send request/response messages to any URI |
+| `WebsocketClient` | Client configuration; instantiate and pass to `WebsocketClientProvider`; `reconnectAllConnections()` for manual retry |
+| `WebsocketClientProvider` | Context provider; wrap your app to enable hooks |
+| `WebsocketConnection` | Low-level connection class; `setCustomLogger` for debugging |
+| `ReadyState`, `WebsocketSubscriptionStore`, `WebsocketTransportError`, `WebsocketServerError` | Types |
 
 ---
 
-## 🔧 Usage & Integration
+## Examples
 
 ### Subscription (Streaming Data)
 
-```typescript
-import { useWebsocketSubscription } from "@max-troost-io/use-websocket";
+Subscribe to a URI and receive streaming data via a reactive TanStack Store.
+
+```tsx
+import { useWebsocketSubscription } from "@maxtroost/use-websocket";
 import { useStore } from "@tanstack/react-store";
 
+interface Voyage {
+  id: string;
+  name: string;
+  status: string;
+}
+
 function VoyageList() {
-  const voyageApi = useWebsocketSubscription<Voyage[], VoyageFilters>({
+  const voyageApi = useWebsocketSubscription<Voyage[], { status: string }>({
     key: "voyages-list",
-    url: "/api",
+    url: "wss://api.example.com/ws",
     uri: "/api/voyages",
     body: { status: "active" },
   });
 
   const voyages = useStore(voyageApi.store, (s) => s.message);
   const pending = useStore(voyageApi.store, (s) => s.pendingSubscription);
+  const connected = useStore(voyageApi.store, (s) => s.connected);
 
   if (pending) return <Skeleton />;
-  return <div>{/* Render voyages */}</div>;
+  return (
+    <div>
+      {!connected && <span>Reconnecting...</span>}
+      {voyages?.map((v) => (
+        <div key={v.id}>{v.name}</div>
+      ))}
+    </div>
+  );
 }
 ```
 
 ### Access Store by Key (Child Components)
 
-```typescript
-import { useWebsocketSubscriptionByKey } from "@max-troost-io/use-websocket";
+When a parent creates the subscription, children can access the same store by key.
+
+```tsx
+import { useWebsocketSubscriptionByKey } from "@maxtroost/use-websocket";
 import { useStore } from "@tanstack/react-store";
 
 function VoyageCount() {
@@ -244,13 +185,15 @@ function VoyageCount() {
 
 ### Message API (Request/Response)
 
-```typescript
-import { useWebsocketMessage } from "@max-troost-io/use-websocket";
+For one-off commands (validate, modify, mark read) — send a message and optionally await a response.
+
+```tsx
+import { useWebsocketMessage } from "@maxtroost/use-websocket";
 
 function VoyageActions() {
-  const api = useWebsocketMessage<ModifyVoyageUim, ModifyVoyageUim>({
+  const api = useWebsocketMessage<ValidationResult, FormValues>({
     key: "voyages/modify",
-    url: "/api",
+    url: "wss://api.example.com/ws",
     responseTimeoutMs: 5000,
   });
 
@@ -260,91 +203,135 @@ function VoyageActions() {
       "post",
       formValues
     );
-    // ...
+    if (result.valid) {
+      // proceed
+    }
   };
 
   const handleMarkRead = () => {
     api.sendMessageNoWait(`notifications/${id}/read`, "post");
   };
+
+  return (
+    <>
+      <button onClick={handleValidate}>Validate</button>
+      <button onClick={handleMarkRead}>Mark Read</button>
+    </>
+  );
 }
 ```
 
-### Options Reference
+### Conditional Subscription
 
-#### WebsocketSubscriptionOptions
+Disable the subscription when the user is not authenticated or when a feature flag is off.
 
-| Option                                                             | Type      | Description                                                            |
-| ------------------------------------------------------------------ | --------- | ---------------------------------------------------------------------- |
-| `key`                                                              | `string`  | Unique identifier; components with same key share the API              |
-| `url`                                                              | `string`  | Base WebSocket path (full URL; apps typically build from auth context) |
-| `uri`                                                              | `string`  | URI endpoint for this subscription                                     |
-| `body`                                                             | `TBody`   | Optional payload for subscription                                      |
-| `enabled`                                                          | `boolean` | When `false`, disconnects (default: `true`)                            |
-| `onMessage`, `onSubscribe`, `onError`, `onMessageError`, `onClose` | callbacks | Lifecycle callbacks                                                    |
-
-#### WebsocketMessageOptions
-
-| Option              | Type      | Description                                        |
-| ------------------- | --------- | -------------------------------------------------- |
-| `key`               | `string`  | Unique identifier                                  |
-| `url`               | `string`  | Base WebSocket path                                |
-| `enabled`           | `boolean` | When `false`, disconnects                          |
-| `responseTimeoutMs` | `number`  | Default timeout for `sendMessage` (default: 10000) |
+```tsx
+function VoyageList({ isAuthenticated }: { isAuthenticated: boolean }) {
+  const api = useWebsocketSubscription<Voyage[]>({
+    key: "voyages-list",
+    url: "wss://api.example.com/ws",
+    uri: "/api/voyages",
+    enabled: isAuthenticated,
+  });
+  // ...
+}
+```
 
 ---
 
-## 🐛 Troubleshooting & Debugging
-
-### Common Issues
+## Advanced Examples
+
+### Custom WebsocketClient Configuration
+
+```tsx
+const websocketClient = new WebsocketClient({
+  maxRetryAttempts: 10,
+  notificationThreshold: 5,
+  messageResponseTimeoutMs: 5000,
+  heartbeat: { enabled: true, intervalMs: 30000 },
+  connectionEvent: (event) => {
+    if (event.type === "reconnecting") {
+      analytics.track("websocket_reconnecting", { url: event.url });
+    }
+  },
+});
+```
 
-#### Subscription Never Receives Data
+### Auth Token in WebSocket URL
 
-- **Symptoms**: `message` stays `undefined`, `pendingSubscription` remains `true`
-- **Possible causes**: Wrong `uri`, server not sending to that URI, connection not open
-- **Debugging**: Check `connected` in store; verify server logs for incoming subscribe; ensure `useWebsocketConnectionConfig` and `useReconnectWebsocketConnections` are called at app root inside auth provider
-- **Solution**: Confirm `uri` matches server route; check network tab for WebSocket frames
+When the WebSocket URL includes an auth token, pass the full URL to the hook. When the token changes, the hook automatically calls `replaceUrl` to reconnect with the new URL.
 
-#### Connection Drops Repeatedly
+```tsx
+function VoyageList() {
+  const { token } = useAuth();
+  const wsUrl = token ? `wss://api.example.com/ws?token=${token}` : null;
 
-- **Symptoms**: Frequent reconnects, notifications after 10 attempts
-- **Possible causes**: Auth token expiry, CORS, wrong URL, server rejecting connection
-- **Debugging**: `WebsocketConnection.setCustomLogger` to log events; check `connectionFailed` callback (token refresh triggered after 5 retries)
-- **Solution**: Pass WebSocket secret via `useWebsocketConnectionConfig` for local dev; verify auth context provides valid region/role for URL construction
+  const api = useWebsocketSubscription<Voyage[]>({
+    key: "voyages",
+    url: wsUrl ?? "", // Hook handles URL changes via replaceUrl
+    uri: "/api/voyages",
+    enabled: !!token,
+  });
+  // ...
+}
+```
 
-#### Child Component Gets Empty Store
+To manually retry after reconnection stops (e.g. user clicks "Retry"): `websocketClient.reconnectAllConnections()`.
 
-- **Symptoms**: `useWebsocketSubscriptionByKey` returns fallback store with `message: undefined`
-- **Possible causes**: Parent with `useWebsocketSubscription` not mounted yet; different `key` used
-- **Debugging**: Ensure parent mounts first; verify `key` string matches exactly
-- **Solution**: Use same `key` in parent and child; consider lifting subscription higher in tree
+### Transform Outgoing Messages (e.g. Add Auth Header)
 
-### Debugging Tools
+```tsx
+const websocketClient = new WebsocketClient({
+  transformMessagePayload: (payload) => ({
+    ...payload,
+    headers: {
+      ...payload.headers,
+      Authorization: `Bearer ${getAuthToken()}`,
+    },
+  }),
+});
+```
 
-- **Browser DevTools**: Network tab → WS filter for WebSocket frames
-- **Debugging**: `WebsocketConnection.setCustomLogger` to log events; check `connectionFailed` callback (token refresh triggered after 5 retries)
-- **Store inspection**: `useStore(api.store)` to read full state
+### Lifecycle Callbacks
+
+```tsx
+const api = useWebsocketSubscription<Voyage[]>({
+  key: "voyages",
+  url: "wss://api.example.com/ws",
+  uri: "/api/voyages",
+  onSubscribe: ({ uri }) => console.log("Subscribed to", uri),
+  onMessage: ({ data }) => console.log("Received", data),
+  onError: (error) => {
+    if (error.type === "transport")
+      console.error("Connection error", error.event);
+  },
+  onMessageError: (error) => {
+    if (error.type === "server")
+      console.error("Server error", error.message);
+  },
+  onClose: (event) => console.log("Connection closed", event.code),
+});
+```
 
-### Error Types
+### Per-Call Timeout Override
 
-- **WebsocketTransportError**: Connection failure, network issues (`error.type === 'transport'`)
-- **WebsocketServerError**: Server-sent error message (`error.type === 'server'`, body in `error.message`)
+```tsx
+const result = await api.sendMessage("/api/command", "post", body, {
+  timeout: 3000,
+});
+```
 
 ---
 
-## 📦 Dependencies
+## Documentation
+
+For contributors and deeper architecture details:
 
-| Dependency              | Purpose                                  |
-| ----------------------- | ---------------------------------------- |
-| `@tanstack/react-store` | Reactive state for components            |
-| `@tanstack/store`       | Core store implementation                |
-| `notistack`             | User notifications (reconnection errors) |
-| `uuid`                  | Correlation IDs                          |
-| `fast-equals`           | Deep equality for options                |
-| `usehooks-ts`           | `useIsomorphicLayoutEffect`              |
+- **[WEBSOCKET_CONNECTION.md](https://github.com/max-troost-io/mt-use-websockets/blob/main/src/lib/WEBSOCKET_CONNECTION.md)** — Connection lifecycle, class diagrams, URI API lifecycle, browser online/offline handling, full API reference
+- **[CHART.md](https://github.com/max-troost-io/mt-use-websockets/blob/main/src/lib/CHART.md)** — Mermaid flow diagrams for hooks, connection, and error flows
 
 ---
 
-## Learn More
+## License
 
-- **[WEBSOCKET_CONNECTION.md](src/lib/WEBSOCKET_CONNECTION.md)** — Detailed architecture, class diagrams, connection lifecycle, URI API lifecycle, browser online/offline handling, full API reference
-- **[CHART.md](CHART.md)** — Mermaid flow diagrams for hooks, connection, and error flows
+MIT