hotpipe 0.0.1 → 0.2.0

package/README.md

@@ -0,0 +1,390 @@
+# hotpipe
+
+Type-safe real-time events for React and Next.js. Define your events with Zod, subscribe with React hooks, publish from client or server. Clients connect directly to the hotpipe API over WebSocket — your Next.js server is never in the hot path.
+
+## Install
+
+```bash
+npm install hotpipe
+```
+
+Peer dependencies: `react` (>=18), `zod` (>=3).
+
+## Quick start
+
+### 1. Create the route handler
+
+Hotpipe uses your existing auth — check the session however you normally do. The `authorize` function runs on every connection attempt. Return `null` to deny access, or return the user's ID and pipe permissions to grant it. We'll cover pipe permissions in detail after the usage examples.
+
+```ts
+// app/api/realtime/[...all]/route.ts
+import { createPipeHandler } from 'hotpipe/server';
+
+export const { POST } = createPipeHandler({
+  secret: process.env.HOTPIPE_SECRET!,
+  authorize: async (req) => {
+    const { session } = await getAuth(req); // your auth
+    if (!session) return null;
+
+    return {
+      userId: session.userId,
+      pipes: {}, // we'll configure these in the permissions section
+    };
+  },
+});
+```
+
+### 2. Define your events
+
+This is your single source of truth for event types across client and server.
+
+```ts
+// lib/realtime-events.ts
+import { z } from 'zod';
+
+export const realtimeEvents = {
+  'message.created': z.object({
+    id: z.string(),
+    text: z.string(),
+    userId: z.string(),
+    createdAt: z.number(),
+  }),
+  'message.deleted': z.object({
+    id: z.string(),
+  }),
+  'typing.start': z.object({
+    userId: z.string(),
+  }),
+} as const;
+```
+
+### 3. Create the client
+
+```ts
+// lib/realtime-client.ts
+import { createPipeClient } from 'hotpipe/client';
+
+import { realtimeEvents } from './realtime-events';
+
+export const { PipeProvider, usePipe } = createPipeClient({
+  events: realtimeEvents,
+});
+```
+
+This assumes your auth uses cookies (the default for most frameworks like Better Auth, NextAuth, and Clerk). If you're using bearer tokens instead, pass an `authHeaders` function:
+
+```ts
+export const { PipeProvider, usePipe } = createPipeClient({
+  events: realtimeEvents,
+  authHeaders: async () => ({
+    Authorization: `Bearer ${getAccessToken()}`,
+  }),
+});
+```
+
+### 4. Add the provider
+
+Wrap your app with `PipeProvider`. This connects everything — your frontend, your backend, and the hotpipe API.
+
+```tsx
+// app/layout.tsx
+import { PipeProvider } from '@/lib/realtime-client';
+
+export default function Layout({ children }: { children: React.ReactNode }) {
+  return <PipeProvider>{children}</PipeProvider>;
+}
+```
+
+### 5. Create the server publisher
+
+You can also publish events from server actions, route handlers, and even background jobs. No limits.
+
+```ts
+// lib/realtime-server.ts
+import { createPipePublisher } from 'hotpipe/server';
+
+import { realtimeEvents } from './realtime-events';
+
+export const realtime = createPipePublisher({
+  secret: process.env.HOTPIPE_SECRET!,
+  events: realtimeEvents,
+});
+```
+
+## Usage
+
+Let's build a team chat. Users type messages, and everyone on the team sees them instantly.
+
+### Listening for new messages
+
+When someone sends a message, every connected user should see it appear. We exported a `usePipe` hook in step 3. This is where you'll use it.
+
+The first argument to `usePipe` is the pipe name — it's just a string, and you can name it anything you want. We're calling this one `"team-chat"` because it's a shared space where everyone on the team sees every message. The second argument is an object of event handlers. When a `message.created` event comes in, our handler runs. The data is fully typed based on the schema you defined in step 2.
+
+```tsx
+import { usePipe } from '@/lib/realtime-client';
+
+function Messages() {
+  const [messages, setMessages] = useState([]);
+
+  usePipe('team-chat', {
+    'message.created': (data) => {
+      setMessages((prev) => [...prev, data]);
+    },
+  });
+
+  return (
+    <ul>
+      {messages.map((msg) => (
+        <li key={msg.id}>{msg.text}</li>
+      ))}
+    </ul>
+  );
+}
+```
+
+A few other pipe names to get your wheels turning:
+
+- `"game-lobby-abc"` — real-time multiplayer game state
+- `"player-xyz"` — events targeting a specific player
+- `"org-acme"` — updates scoped to a whole organization
+- `"doc-789"` — collaborative editing on a shared document
+- `"auction-42"` — live bid updates on a specific item
+
+The name is up to you. Whatever makes sense for your app.
+
+### Sending a message from the browser
+
+The same `usePipe` hook also gives you a `publish` function. When a user hits send, the event goes out to everyone listening on that pipe.
+
+Hotpipe doesn't store anything — it's purely real-time delivery. You save data however you normally do (server actions, API calls, etc.) and publish the event alongside it.
+
+```tsx
+function MessageInput() {
+  const [text, setText] = useState('');
+  const { publish } = usePipe('team-chat');
+
+  async function send() {
+    // save to your database first
+    const message = await createMessage({ text, userId: currentUser.id });
+
+    // then broadcast it to everyone in real time
+    publish('message.created', {
+      id: message.id,
+      text: message.text,
+      userId: message.userId,
+      createdAt: message.createdAt,
+    });
+
+    setText('');
+  }
+
+  return (
+    <form
+      onSubmit={(e) => {
+        e.preventDefault();
+        send();
+      }}
+    >
+      <input value={text} onChange={(e) => setText(e.target.value)} />
+      <button type="submit">Send</button>
+    </form>
+  );
+}
+```
+
+### Sending events from the server
+
+Same idea on the server. Maybe you're already saving data in a server action or handling a webhook — just publish the event after. Everyone listening on that pipe gets it instantly.
+
+```ts
+import { realtime } from '@/lib/realtime-server';
+
+// save to your database
+const message = await db.messages.create({ text, userId });
+
+// broadcast to connected users
+const teamChat = realtime.pipe('team-chat');
+
+await teamChat.publish('message.created', {
+  id: message.id,
+  text: message.text,
+  userId: message.userId,
+  createdAt: message.createdAt,
+});
+```
+
+### Connection status
+
+You can check whether the user is connected to the hotpipe API at any time.
+
+```tsx
+const { status } = usePipe('team-chat');
+// 'connecting' | 'connected' | 'disconnected' | 'reconnecting'
+```
+
+Hotpipe automatically reconnects if the connection drops.
+
+## Pipes and permissions
+
+Now that you've seen how pipes work in practice, let's go back to the `authorize` function from step 1 and talk about access control.
+
+Every user who connects gets a set of pipe permissions. You define these in the object returned by `authorize`. Each pipe can grant two abilities: `subscribe` (receive events) and `publish` (send events).
+
+### Team chat — everyone can read and write
+
+In the chat example above, every team member should be able to send and receive messages. Give everyone both permissions on the `team-chat` pipe:
+
+```ts
+authorize: async (req) => {
+  const { session } = await getAuth(req);
+  if (!session) return null;
+
+  return {
+    userId: session.userId,
+    pipes: {
+      'team-chat': { subscribe: true, publish: true },
+    },
+  };
+},
+```
+
+### User-specific pipes — scoped to a single user
+
+Sometimes you need to send events to a specific user — a notification, a status update, something only they should see. Use a dynamic pipe name with their user ID:
+
+```ts
+return {
+  userId: session.userId,
+  pipes: {
+    [`user-${session.userId}`]: { subscribe: true },
+  },
+};
+```
+
+Now your server can publish to `user-abc123` and only that user receives it. Other users can't subscribe to someone else's pipe because it's not in their permissions.
+
+### Read-only pipes — broadcast without client publish
+
+For things like live dashboards, announcements, or system alerts, you might want users to receive events but not send them. Only grant `subscribe`:
+
+```ts
+return {
+  userId: session.userId,
+  pipes: {
+    announcements: { subscribe: true },
+  },
+};
+```
+
+The server can publish to `announcements` anytime. Clients can listen but can't push events to this pipe.
+
+### Combining pipes — a real-world example
+
+Most apps need a mix. Here's what a team collaboration app might look like:
+
+```ts
+authorize: async (req) => {
+  const { session } = await getAuth(req);
+  if (!session) return null;
+
+  const teamId = await getTeamId(session.userId);
+
+  return {
+    userId: session.userId,
+    pipes: {
+      [`team-${teamId}`]: { subscribe: true, publish: true },
+      [`user-${session.userId}`]: { subscribe: true },
+      'announcements': { subscribe: true },
+    },
+  };
+},
+```
+
+Three pipes, three different access patterns:
+
+- **`team-abc`** — everyone on the team can send and receive (chat, typing indicators, live cursors)
+- **`user-xyz`** — only this user receives (notifications, direct messages from the server)
+- **`announcements`** — all users receive, only the server publishes (maintenance alerts, feature launches)
+
+If a user tries to subscribe or publish to a pipe that isn't in their permissions, the API ignores the request.
+
+## Environment variables
+
+| Variable         | Where  | Description                                           |
+| ---------------- | ------ | ----------------------------------------------------- |
+| `HOTPIPE_SECRET` | Server | Shared secret for auth tokens and server-side publish |
+
+## How it works
+
+1. User loads your app
+2. `PipeProvider` calls your handler to get an auth token
+3. Your handler checks the session and signs a JWT with pipe permissions
+4. The client opens a WebSocket directly to the hotpipe API
+5. Events flow between clients and server through the hotpipe API
+6. Your Next.js server is out of the loop — no long-lived connections, no Vercel cost impact
+
+The hotpipe API is stateless. It handles connection management and event fan-out. Your database is the source of truth — the API doesn't persist anything.
+
+## API reference
+
+### `hotpipe/client`
+
+#### `createPipeClient(config)`
+
+Returns `{ PipeProvider, usePipe }`.
+
+| Option        | Type                                    | Required | Description                                                 |
+| ------------- | --------------------------------------- | -------- | ----------------------------------------------------------- |
+| `events`      | `Record<string, ZodType>`               | Yes      | Zod schemas for your events                                 |
+| `basePath`    | `string`                                | No       | Where your handler is mounted (defaults to `/api/realtime`) |
+| `authHeaders` | `() => Promise<Record<string, string>>` | No       | Custom headers for the auth request (e.g., bearer tokens)   |
+
+#### `PipeProvider`
+
+Wrap your app (or a subtree) to establish the WebSocket connection to the hotpipe API. Connects on mount, disconnects on unmount.
+
+#### `usePipe(pipe, handlers?)`
+
+Subscribe to events on a pipe.
+
+| Argument   | Type                                       | Description                                          |
+| ---------- | ------------------------------------------ | ---------------------------------------------------- |
+| `pipe`     | `string`                                   | The pipe name to subscribe to                        |
+| `handlers` | `{ [event]: (data) => void }` _(optional)_ | Event handlers, keyed by event name from your schema |
+
+Returns `{ status, publish }`:
+
+- **`status`** — Reactive connection state: `'connecting'`, `'connected'`, `'disconnected'`, or `'reconnecting'`. Updates automatically and triggers a re-render on change.
+- **`publish(event, data)`** — Send a typed event to everyone on this pipe. Data is validated against your Zod schema before sending. Returns `true` if the event was sent or queued for delivery, `false` if the queue is full. Throws if the data fails validation. If the connection is temporarily down, events are buffered and flushed automatically when the connection comes back (up to 100 events, within 30 seconds).
+
+The hook automatically subscribes when the component mounts and unsubscribes when it unmounts. If multiple components subscribe to the same pipe, hotpipe ref-counts them — the subscription stays active until the last component unmounts.
+
+### `hotpipe/server`
+
+#### `createPipeHandler(config)`
+
+Returns `{ POST }` for your catch-all route handler.
+
+| Option        | Type                                            | Required | Description                               |
+| ------------- | ----------------------------------------------- | -------- | ----------------------------------------- |
+| `secret`      | `string`                                        | Yes      | Shared signing secret                     |
+| `authorize`   | `(req: Request) => Promise<AuthResult \| null>` | Yes      | Your auth logic                           |
+| `tokenExpiry` | `number`                                        | No       | Token lifetime in seconds (default: 3600) |
+
+#### `createPipePublisher(config)`
+
+Returns `{ pipe }`.
+
+| Option   | Type                      | Required | Description                 |
+| -------- | ------------------------- | -------- | --------------------------- |
+| `secret` | `string`                  | Yes      | Your hotpipe secret         |
+| `events` | `Record<string, ZodType>` | Yes      | Zod schemas for your events |
+
+#### `publisher.pipe(name)`
+
+Returns `{ publish }` for server-side event publishing. Unlike the client-side `publish`, this is async — it makes an HTTP request to the hotpipe API and will throw if the request fails.
+
+## License
+
+MIT

package/dist/client/connection.d.ts

@@ -0,0 +1,39 @@
+export type ConnectionStatus = 'disconnected' | 'connecting' | 'connected' | 'reconnecting';
+export type PipeListener = (event: string, data: unknown) => void;
+interface ConnectionConfig {
+    brokerUrl: string;
+    authEndpoint: string;
+    authHeaders?: () => Promise<Record<string, string>>;
+}
+export declare class ConnectionManager {
+    private config;
+    private ws;
+    private status;
+    private statusListeners;
+    private pipeListeners;
+    private pipeRefs;
+    private reconnectAttempts;
+    private maxReconnectDelay;
+    private pingInterval;
+    private reconnectTimer;
+    private intentionalClose;
+    private eventQueue;
+    constructor(config: ConnectionConfig);
+    connect(): Promise<void>;
+    disconnect(): void;
+    subscribe(pipe: string): void;
+    unsubscribe(pipe: string): void;
+    publish(pipe: string, event: string, data: unknown): boolean;
+    addPipeListener(pipe: string, listener: PipeListener): void;
+    removePipeListener(pipe: string, listener: PipeListener): void;
+    getStatus(): ConnectionStatus;
+    onStatusChange(listener: (status: ConnectionStatus) => void): () => void;
+    private flushQueue;
+    private dispatch;
+    private setStatus;
+    private wsSend;
+    private cleanup;
+    private scheduleReconnect;
+}
+export {};
+//# sourceMappingURL=connection.d.ts.map

package/dist/client/connection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.d.ts","sourceRoot":"","sources":["../../src/client/connection.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,gBAAgB,GAAG,cAAc,GAAG,YAAY,GAAG,WAAW,GAAG,cAAc,CAAC;AAE5F,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,IAAI,CAAC;AAElE,UAAU,gBAAgB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;AAYD,qBAAa,iBAAiB;IAahB,OAAO,CAAC,MAAM;IAZ1B,OAAO,CAAC,EAAE,CAA0B;IACpC,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,eAAe,CAAiD;IACxE,OAAO,CAAC,aAAa,CAAwC;IAC7D,OAAO,CAAC,QAAQ,CAA6B;IAC7C,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,iBAAiB,CAAU;IACnC,OAAO,CAAC,YAAY,CAA+C;IACnE,OAAO,CAAC,cAAc,CAA8C;IACpE,OAAO,CAAC,gBAAgB,CAAS;IACjC,OAAO,CAAC,UAAU,CAAqB;gBAEnB,MAAM,EAAE,gBAAgB;IAEtC,OAAO;IA2Eb,UAAU;IAeV,SAAS,CAAC,IAAI,EAAE,MAAM;IAStB,WAAW,CAAC,IAAI,EAAE,MAAM;IAcxB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO;IAkB5D,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY;IAQpD,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,YAAY;IAQvD,SAAS,IAAI,gBAAgB;IAI7B,cAAc,CAAC,QAAQ,EAAE,CAAC,MAAM,EAAE,gBAAgB,KAAK,IAAI,GAAG,MAAM,IAAI;IAKxE,OAAO,CAAC,UAAU;IAUlB,OAAO,CAAC,QAAQ;IAShB,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,MAAM;IAId,OAAO,CAAC,OAAO;IAOf,OAAO,CAAC,iBAAiB;CAW1B"}

package/dist/client/connection.js

@@ -0,0 +1,184 @@
+import { SDK_VERSION } from '../version';
+const MAX_QUEUE_SIZE = 100;
+const QUEUE_TTL = 30_000;
+export class ConnectionManager {
+    config;
+    ws = null;
+    status = 'disconnected';
+    statusListeners = new Set();
+    pipeListeners = new Map();
+    pipeRefs = new Map();
+    reconnectAttempts = 0;
+    maxReconnectDelay = 30_000;
+    pingInterval = null;
+    reconnectTimer = null;
+    intentionalClose = false;
+    eventQueue = [];
+    constructor(config) {
+        this.config = config;
+    }
+    async connect() {
+        if (this.status === 'connecting' || this.status === 'connected')
+            return;
+        this.intentionalClose = false;
+        this.setStatus(this.reconnectAttempts > 0 ? 'reconnecting' : 'connecting');
+        try {
+            const headers = this.config.authHeaders ? await this.config.authHeaders() : undefined;
+            const res = await fetch(this.config.authEndpoint, {
+                method: 'POST',
+                credentials: 'include',
+                headers,
+            });
+            if (!res.ok) {
+                throw new Error(`Auth failed: ${res.status}`);
+            }
+            const { token } = await res.json();
+            const wsUrl = `${this.config.brokerUrl}/ws?token=${encodeURIComponent(token)}&v=${SDK_VERSION}`;
+            this.ws = new WebSocket(wsUrl);
+            this.ws.onopen = () => {
+                this.setStatus('connected');
+                this.reconnectAttempts = 0;
+                // Resubscribe to all active pipes
+                for (const pipe of this.pipeRefs.keys()) {
+                    this.wsSend({ type: 'subscribe', pipe });
+                }
+                // Flush queued events
+                this.flushQueue();
+                // Keepalive ping every 30s
+                this.pingInterval = setInterval(() => {
+                    this.wsSend({ type: 'ping' });
+                }, 30_000);
+            };
+            this.ws.onmessage = (event) => {
+                try {
+                    const msg = JSON.parse(event.data);
+                    if (msg.type === 'event') {
+                        this.dispatch(msg.pipe, msg.event, msg.data);
+                    }
+                }
+                catch {
+                    // Ignore malformed messages
+                }
+            };
+            this.ws.onclose = () => {
+                this.cleanup();
+                this.setStatus('disconnected');
+                if (!this.intentionalClose) {
+                    this.scheduleReconnect();
+                }
+            };
+            this.ws.onerror = () => {
+                // onclose fires after onerror — reconnect handled there
+            };
+        }
+        catch {
+            this.setStatus('disconnected');
+            if (!this.intentionalClose) {
+                this.scheduleReconnect();
+            }
+        }
+    }
+    disconnect() {
+        this.intentionalClose = true;
+        this.cleanup();
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        this.ws?.close();
+        this.ws = null;
+        this.eventQueue = [];
+        this.setStatus('disconnected');
+    }
+    subscribe(pipe) {
+        const count = this.pipeRefs.get(pipe) || 0;
+        this.pipeRefs.set(pipe, count + 1);
+        if (count === 0 && this.ws?.readyState === WebSocket.OPEN) {
+            this.wsSend({ type: 'subscribe', pipe });
+        }
+    }
+    unsubscribe(pipe) {
+        const count = this.pipeRefs.get(pipe) || 0;
+        if (count <= 1) {
+            this.pipeRefs.delete(pipe);
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.wsSend({ type: 'unsubscribe', pipe });
+            }
+        }
+        else {
+            this.pipeRefs.set(pipe, count - 1);
+        }
+    }
+    publish(pipe, event, data) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.wsSend({ type: 'publish', pipe, event, data });
+            return true;
+        }
+        if (this.intentionalClose) {
+            return false;
+        }
+        if (this.eventQueue.length >= MAX_QUEUE_SIZE) {
+            return false;
+        }
+        this.eventQueue.push({ pipe, event, data, timestamp: Date.now() });
+        return true;
+    }
+    addPipeListener(pipe, listener) {
+        if (!this.pipeListeners.has(pipe)) {
+            this.pipeListeners.set(pipe, new Set());
+        }
+        this.pipeListeners.get(pipe).add(listener);
+    }
+    removePipeListener(pipe, listener) {
+        this.pipeListeners.get(pipe)?.delete(listener);
+        if (this.pipeListeners.get(pipe)?.size === 0) {
+            this.pipeListeners.delete(pipe);
+        }
+    }
+    getStatus() {
+        return this.status;
+    }
+    onStatusChange(listener) {
+        this.statusListeners.add(listener);
+        return () => this.statusListeners.delete(listener);
+    }
+    flushQueue() {
+        const now = Date.now();
+        const pending = this.eventQueue.filter((e) => now - e.timestamp < QUEUE_TTL);
+        this.eventQueue = [];
+        for (const { pipe, event, data } of pending) {
+            this.wsSend({ type: 'publish', pipe, event, data });
+        }
+    }
+    dispatch(pipe, event, data) {
+        const listeners = this.pipeListeners.get(pipe);
+        if (!listeners)
+            return;
+        for (const listener of listeners) {
+            listener(event, data);
+        }
+    }
+    setStatus(status) {
+        this.status = status;
+        for (const listener of this.statusListeners) {
+            listener(status);
+        }
+    }
+    wsSend(msg) {
+        this.ws?.send(JSON.stringify(msg));
+    }
+    cleanup() {
+        if (this.pingInterval) {
+            clearInterval(this.pingInterval);
+            this.pingInterval = null;
+        }
+    }
+    scheduleReconnect() {
+        const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts) + Math.random() * 1000, this.maxReconnectDelay);
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectAttempts++;
+            this.connect();
+        }, delay);
+    }
+}
+//# sourceMappingURL=connection.js.map

package/dist/client/connection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection.js","sourceRoot":"","sources":["../../src/client/connection.ts"],"names":[],"mappings":"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"}

package/dist/client/index.d.ts

@@ -0,0 +1,49 @@
+import type { z } from 'zod';
+import { type ConnectionStatus } from './connection';
+/**
+ * A record mapping event names to Zod schemas.
+ */
+type EventMap = Record<string, z.ZodType>;
+/**
+ * Extract event names from an EventMap.
+ */
+type EventName<T extends EventMap> = keyof T & string;
+/**
+ * Infer the data type for a given event.
+ */
+type EventData<T extends EventMap, E extends EventName<T>> = z.infer<T[E]>;
+/**
+ * Handler map for usePipe — a partial record of event handlers.
+ */
+type PipeHandlers<T extends EventMap> = {
+    [E in EventName<T>]?: (data: EventData<T, E>) => void;
+};
+/**
+ * Creates a typed real-time client bound to your event schemas.
+ *
+ * Usage:
+ * ```ts
+ * const { PipeProvider, usePipe } = createPipeClient({
+ *   events: realtimeEvents,
+ * });
+ * ```
+ */
+export declare function createPipeClient<T extends EventMap>(config: {
+    events: T;
+    /** Override the base path where your handler is mounted. Defaults to `/api/realtime`. */
+    basePath?: string;
+    /** @internal Override the broker URL for local development. */
+    brokerUrl?: string;
+    /** Provide custom headers for the auth request (e.g., a Bearer token). */
+    authHeaders?: () => Promise<Record<string, string>>;
+}): {
+    PipeProvider: ({ children }: {
+        children: React.ReactNode;
+    }) => import("react/jsx-runtime").JSX.Element;
+    usePipe: (pipe: string, handlers?: Partial<PipeHandlers<T>>) => {
+        status: ConnectionStatus;
+        publish: <E extends EventName<T>>(event: E, data: EventData<T, E>) => boolean;
+    };
+};
+export type { ConnectionStatus, EventMap };
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.tsx"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAExE;;GAEG;AACH,KAAK,QAAQ,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC;AAE1C;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,QAAQ,IAAI,MAAM,CAAC,GAAG,MAAM,CAAC;AAEtD;;GAEG;AACH,KAAK,SAAS,CAAC,CAAC,SAAS,QAAQ,EAAE,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAE3E;;GAEG;AACH,KAAK,YAAY,CAAC,CAAC,SAAS,QAAQ,IAAI;KACrC,CAAC,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,IAAI;CACtD,CAAC;AAKF;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,QAAQ,EAAE,MAAM,EAAE;IAC3D,MAAM,EAAE,CAAC,CAAC;IACV,yFAAyF;IACzF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,WAAW,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CACrD;iCAiBqC;QAAE,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAA;KAAE;oBAgCzD,MAAM,aACD,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC,KAClC;QACD,MAAM,EAAE,gBAAgB,CAAC;QACzB,OAAO,EAAE,CAAC,CAAC,SAAS,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,SAAS,CAAC,CAAC,EAAE,CAAC,CAAC,KAAK,OAAO,CAAC;KAC/E;EAoDF;AAED,YAAY,EAAE,gBAAgB,EAAE,QAAQ,EAAE,CAAC"}