@voyant-travel/realtime-react 0.1.0

package/README.md

@@ -0,0 +1,84 @@
+# @voyant-travel/realtime-react
+
+React hooks that make existing admin/portal screens live, consuming the channels
+published by [`@voyant-travel/realtime`](../realtime). Vendor-agnostic — the
+transport is injected as a `RealtimeConnector`.
+
+Implements the React half of [RFC #1695](https://github.com/voyant-travel/voyant/issues/1695).
+
+## Hooks
+
+- **`useLiveQueries(channels, map)`** — the one most screens need. Subscribes to
+  channels and translates each invalidation hint into
+  `queryClient.invalidateQueries` calls, so screens go live without rewriting
+  their data layer.
+- **`useChannel(channel, { onMessage, onPresence })`** — subscribe to a single
+  channel with auto token-mint, reconnect, and `sinceId` resume (vendor
+  permitting).
+- **`usePresence(channel, profile)`** — member list ("Ana is viewing this
+  booking").
+
+## Setup
+
+```tsx
+import { RealtimeChannel } from "@voyant-travel/cloud-sdk"
+import {
+  createRealtimeChannelConnector,
+  RealtimeReactProvider,
+} from "@voyant-travel/realtime-react"
+
+// Adapt the Voyant Cloud RealtimeChannel into a connector.
+const connector = createRealtimeChannelConnector(RealtimeChannel, { baseUrl: "/api" })
+
+<QueryClientProvider client={queryClient}>
+  <RealtimeReactProvider connector={connector} tokenEndpoint="/v1/admin/realtime/token">
+    <App />
+  </RealtimeReactProvider>
+</QueryClientProvider>
+```
+
+`connector` is the injection seam: `createRealtimeChannelConnector` wraps the
+cloud-sdk client, but any vendor (Ably, Pusher, a raw WebSocket/SSE wrapper)
+works by implementing `RealtimeConnector` directly.
+
+## Making the dashboard live
+
+Replace the 60s polling fallback with hint-driven invalidation — keep the
+interval as a safety net:
+
+```tsx
+import { useLiveQueries } from "@voyant-travel/realtime-react"
+import { dashboardQueryKeys } from "@voyant-travel/admin/dashboard/query-options"
+
+function DashboardLive() {
+  useLiveQueries(["admin"], (hint) => {
+    switch (hint.entity) {
+      case "booking":
+        return [dashboardQueryKeys.bookingsAggregates()]
+      case "invoice":
+        return [dashboardQueryKeys.financeAggregates()]
+      default:
+        return []
+    }
+  })
+  return null
+}
+```
+
+A missed hint self-heals on the next `staleTime` tick, so at-most-once delivery
+is fine — keep `staleTime: 60_000` as the floor.
+
+## The connector interface
+
+```ts
+interface RealtimeConnector {
+  subscribe(options: {
+    channel: string
+    token: string
+    onMessage?: (message: { event: string; data: unknown }) => void
+    onPresence?: (members: ReadonlyArray<{ clientId: string; profile?: unknown }>) => void
+    sinceId?: string
+    profile?: unknown
+  }): { unsubscribe(): void }
+}
+```

package/dist/connector-cloud.d.ts

@@ -0,0 +1,50 @@
+import type { RealtimeConnector } from "./connector.js";
+/**
+ * Structural subset of the cloud-sdk `RealtimeChannel` this adapter depends on.
+ * Declared locally so `@voyant-travel/realtime-react` stays decoupled from
+ * `@voyant-travel/cloud-sdk` — callers inject the real constructor.
+ *
+ * @see https://github.com/voyant-travel/cloud-sdk/pull/23
+ */
+export interface CloudRealtimeMessage {
+    event: string;
+    data: unknown;
+}
+export interface CloudRealtimePresenceEvent {
+    action: "enter" | "leave" | "update";
+    clientId: string;
+    data?: unknown;
+}
+export interface RealtimeChannelLike {
+    on(event: "message", handler: (message: CloudRealtimeMessage) => void): () => void;
+    on(event: "presence", handler: (event: CloudRealtimePresenceEvent) => void): () => void;
+    enterPresence(data?: unknown): void;
+    close(): void;
+}
+export interface RealtimeChannelCtorOptions {
+    channel: string;
+    token: string;
+    baseUrl?: string;
+    sinceId?: string;
+}
+export type RealtimeChannelCtor = new (options: RealtimeChannelCtorOptions) => RealtimeChannelLike;
+export interface CreateRealtimeChannelConnectorOptions {
+    /** HTTP(S) API origin forwarded to each channel (converted to ws(s)://). */
+    baseUrl?: string;
+}
+/**
+ * Adapt the cloud-sdk `RealtimeChannel` constructor into a vendor-agnostic
+ * {@link RealtimeConnector} for the hooks. Inject the constructor so this stays
+ * decoupled from the SDK:
+ *
+ * ```ts
+ * import { RealtimeChannel } from "@voyant-travel/cloud-sdk"
+ * const connector = createRealtimeChannelConnector(RealtimeChannel, { baseUrl })
+ * ```
+ *
+ * Presence is tracked incrementally from `enter`/`update`/`leave` events into a
+ * member list; subscribers that need the full set on connect should seed it
+ * from `client.realtime.presence.get(channel)`.
+ */
+export declare function createRealtimeChannelConnector(RealtimeChannelCtor: RealtimeChannelCtor, options?: CreateRealtimeChannelConnectorOptions): RealtimeConnector;
+//# sourceMappingURL=connector-cloud.d.ts.map

package/dist/connector-cloud.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector-cloud.d.ts","sourceRoot":"","sources":["../src/connector-cloud.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkB,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEvE;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACnC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC,MAAM,EAAE,OAAO,GAAG,OAAO,GAAG,QAAQ,CAAA;IACpC,QAAQ,EAAE,MAAM,CAAA;IAChB,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,OAAO,EAAE,oBAAoB,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IAClF,EAAE,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,CAAC,KAAK,EAAE,0BAA0B,KAAK,IAAI,GAAG,MAAM,IAAI,CAAA;IACvF,aAAa,CAAC,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAA;IACnC,KAAK,IAAI,IAAI,CAAA;CACd;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,MAAM,CAAA;IACf,KAAK,EAAE,MAAM,CAAA;IACb,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,MAAM,MAAM,mBAAmB,GAAG,KAAK,OAAO,EAAE,0BAA0B,KAAK,mBAAmB,CAAA;AAElG,MAAM,WAAW,qCAAqC;IACpD,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,8BAA8B,CAC5C,mBAAmB,EAAE,mBAAmB,EACxC,OAAO,GAAE,qCAA0C,GAClD,iBAAiB,CA8CnB"}

package/dist/connector-cloud.js

@@ -0,0 +1,52 @@
+/**
+ * Adapt the cloud-sdk `RealtimeChannel` constructor into a vendor-agnostic
+ * {@link RealtimeConnector} for the hooks. Inject the constructor so this stays
+ * decoupled from the SDK:
+ *
+ * ```ts
+ * import { RealtimeChannel } from "@voyant-travel/cloud-sdk"
+ * const connector = createRealtimeChannelConnector(RealtimeChannel, { baseUrl })
+ * ```
+ *
+ * Presence is tracked incrementally from `enter`/`update`/`leave` events into a
+ * member list; subscribers that need the full set on connect should seed it
+ * from `client.realtime.presence.get(channel)`.
+ */
+export function createRealtimeChannelConnector(RealtimeChannelCtor, options = {}) {
+    return {
+        subscribe({ channel, token, sinceId, profile, onMessage, onPresence }) {
+            const channelClient = new RealtimeChannelCtor({
+                channel,
+                token,
+                ...(sinceId !== undefined ? { sinceId } : {}),
+                ...(options.baseUrl !== undefined ? { baseUrl: options.baseUrl } : {}),
+            });
+            const teardown = [];
+            if (onMessage) {
+                teardown.push(channelClient.on("message", (message) => onMessage({ event: message.event, data: message.data })));
+            }
+            if (onPresence) {
+                const members = new Map();
+                teardown.push(channelClient.on("presence", (event) => {
+                    if (event.action === "leave") {
+                        members.delete(event.clientId);
+                    }
+                    else {
+                        members.set(event.clientId, { clientId: event.clientId, profile: event.data });
+                    }
+                    onPresence([...members.values()]);
+                }));
+            }
+            if (profile !== undefined) {
+                channelClient.enterPresence(profile);
+            }
+            return {
+                unsubscribe() {
+                    for (const off of teardown)
+                        off();
+                    channelClient.close();
+                },
+            };
+        },
+    };
+}

package/dist/connector.d.ts

@@ -0,0 +1,39 @@
+/**
+ * A realtime message as seen by the browser. Mirrors the server-side
+ * `RealtimeMessage` from `@voyant-travel/realtime`; for the EventBus bridge the
+ * `data` is a `RealtimeInvalidationHint`.
+ */
+export interface RealtimeClientMessage {
+    event: string;
+    data: unknown;
+}
+/** A presence member published by the transport. */
+export interface PresenceMember {
+    clientId: string;
+    profile?: unknown;
+}
+export interface RealtimeSubscribeOptions {
+    channel: string;
+    /** Short-lived client token minted by the realtime token route. */
+    token: string;
+    onMessage?: (message: RealtimeClientMessage) => void;
+    onPresence?: (members: ReadonlyArray<PresenceMember>) => void;
+    /** Resume marker for at-least-once vendors that support replay. */
+    sinceId?: string;
+    /** Local presence profile announced to the channel's member set. */
+    profile?: unknown;
+}
+/** A live subscription handle. */
+export interface RealtimeConnection {
+    unsubscribe(): void;
+}
+/**
+ * Vendor-specific browser transport. This is the injection seam that keeps the
+ * hooks vendor-agnostic: Voyant Cloud ships a connector backed by its
+ * `RealtimeChannel` client, and self-hosters pass their own (Ably, Pusher,
+ * a raw WebSocket/SSE wrapper, …).
+ */
+export interface RealtimeConnector {
+    subscribe(options: RealtimeSubscribeOptions): RealtimeConnection;
+}
+//# sourceMappingURL=connector.d.ts.map

package/dist/connector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connector.d.ts","sourceRoot":"","sources":["../src/connector.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,IAAI,EAAE,OAAO,CAAA;CACd;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC,OAAO,EAAE,MAAM,CAAA;IACf,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,IAAI,CAAA;IAC7D,mEAAmE;IACnE,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,kCAAkC;AAClC,MAAM,WAAW,kBAAkB;IACjC,WAAW,IAAI,IAAI,CAAA;CACpB;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,OAAO,EAAE,wBAAwB,GAAG,kBAAkB,CAAA;CACjE"}

package/dist/connector.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export type { PresenceMember, RealtimeClientMessage, RealtimeConnection, RealtimeConnector, RealtimeSubscribeOptions, } from "./connector.js";
+export type { CreateRealtimeChannelConnectorOptions, RealtimeChannelCtor, RealtimeChannelCtorOptions, RealtimeChannelLike, } from "./connector-cloud.js";
+export { createRealtimeChannelConnector } from "./connector-cloud.js";
+export type { RealtimeReactContextValue, RealtimeReactProviderProps, RealtimeTokenFetcher, } from "./provider.js";
+export { RealtimeReactProvider, useRealtimeContext } from "./provider.js";
+export type { HintToQueryKeys, RealtimeInvalidationHint, } from "./query-keys.js";
+export { resolveInvalidationKeys } from "./query-keys.js";
+export type { UseChannelOptions } from "./use-channel.js";
+export { useChannel } from "./use-channel.js";
+export type { UseLiveQueriesOptions } from "./use-live-queries.js";
+export { useLiveQueries } from "./use-live-queries.js";
+export { usePresence } from "./use-presence.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,cAAc,EACd,qBAAqB,EACrB,kBAAkB,EAClB,iBAAiB,EACjB,wBAAwB,GACzB,MAAM,gBAAgB,CAAA;AACvB,YAAY,EACV,qCAAqC,EACrC,mBAAmB,EACnB,0BAA0B,EAC1B,mBAAmB,GACpB,MAAM,sBAAsB,CAAA;AAC7B,OAAO,EAAE,8BAA8B,EAAE,MAAM,sBAAsB,CAAA;AACrE,YAAY,EACV,yBAAyB,EACzB,0BAA0B,EAC1B,oBAAoB,GACrB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAA;AACzE,YAAY,EACV,eAAe,EACf,wBAAwB,GACzB,MAAM,iBAAiB,CAAA;AACxB,OAAO,EAAE,uBAAuB,EAAE,MAAM,iBAAiB,CAAA;AACzD,YAAY,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAA;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAA;AACtD,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAA"}

package/dist/index.js

@@ -0,0 +1,6 @@
+export { createRealtimeChannelConnector } from "./connector-cloud.js";
+export { RealtimeReactProvider, useRealtimeContext } from "./provider.js";
+export { resolveInvalidationKeys } from "./query-keys.js";
+export { useChannel } from "./use-channel.js";
+export { useLiveQueries } from "./use-live-queries.js";
+export { usePresence } from "./use-presence.js";

package/dist/provider.d.ts

@@ -0,0 +1,28 @@
+import { type ReactNode } from "react";
+import type { RealtimeConnector } from "./connector.js";
+export type RealtimeTokenFetcher = () => Promise<{
+    token: string;
+    expiresAt: string;
+}>;
+export interface RealtimeReactContextValue {
+    connector: RealtimeConnector;
+    /** Fetches a fresh client token from the deployment's token-mint route. */
+    fetchToken: RealtimeTokenFetcher;
+}
+export interface RealtimeReactProviderProps {
+    /** Vendor-specific browser transport (Voyant Cloud, Ably, Pusher, …). */
+    connector: RealtimeConnector;
+    /**
+     * Token endpoint to call for a scoped client token. Defaults to
+     * `/v1/public/realtime/token` (use the admin path for staff surfaces).
+     */
+    tokenEndpoint?: string;
+    /** Override the fetch implementation (defaults to credentialed `fetch`). */
+    fetcher?: (url: string, init?: RequestInit) => Promise<Response>;
+    /** Fully override token retrieval (takes precedence over `tokenEndpoint`). */
+    fetchToken?: RealtimeTokenFetcher;
+    children: ReactNode;
+}
+export declare function RealtimeReactProvider({ connector, tokenEndpoint, fetcher, fetchToken, children, }: RealtimeReactProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useRealtimeContext(): RealtimeReactContextValue;
+//# sourceMappingURL=provider.d.ts.map

package/dist/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../src/provider.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAiB,KAAK,SAAS,EAAuB,MAAM,OAAO,CAAA;AAE1E,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AAEvD,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,CAAA;AAEtF,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,iBAAiB,CAAA;IAC5B,2EAA2E;IAC3E,UAAU,EAAE,oBAAoB,CAAA;CACjC;AAID,MAAM,WAAW,0BAA0B;IACzC,yEAAyE;IACzE,SAAS,EAAE,iBAAiB,CAAA;IAC5B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,4EAA4E;IAC5E,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,WAAW,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAA;IAChE,8EAA8E;IAC9E,UAAU,CAAC,EAAE,oBAAoB,CAAA;IACjC,QAAQ,EAAE,SAAS,CAAA;CACpB;AAKD,wBAAgB,qBAAqB,CAAC,EACpC,SAAS,EACT,aAA2C,EAC3C,OAAwB,EACxB,UAAU,EACV,QAAQ,GACT,EAAE,0BAA0B,2CAgB5B;AAED,wBAAgB,kBAAkB,IAAI,yBAAyB,CAQ9D"}

package/dist/provider.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+const RealtimeReactContext = createContext(null);
+const defaultFetcher = (url, init) => fetch(url, { credentials: "include", ...init });
+export function RealtimeReactProvider({ connector, tokenEndpoint = "/v1/public/realtime/token", fetcher = defaultFetcher, fetchToken, children, }) {
+    const value = useMemo(() => {
+        const resolveToken = fetchToken ??
+            (async () => {
+                const response = await fetcher(tokenEndpoint, { method: "POST" });
+                if (!response.ok) {
+                    throw new Error(`Realtime token request failed: ${response.status}`);
+                }
+                const body = (await response.json());
+                return { token: body.data.token, expiresAt: body.data.expiresAt };
+            });
+        return { connector, fetchToken: resolveToken };
+    }, [connector, tokenEndpoint, fetcher, fetchToken]);
+    return _jsx(RealtimeReactContext.Provider, { value: value, children: children });
+}
+export function useRealtimeContext() {
+    const context = useContext(RealtimeReactContext);
+    if (!context) {
+        throw new Error("useRealtimeContext must be used inside <RealtimeReactProvider>. Wrap your app with <RealtimeReactProvider connector={...} />.");
+    }
+    return context;
+}

package/dist/query-keys.d.ts

@@ -0,0 +1,24 @@
+import type { QueryKey } from "@tanstack/react-query";
+import type { RealtimeClientMessage } from "./connector.js";
+/**
+ * The invalidation hint shape published by the `@voyant-travel/realtime`
+ * EventBus bridge.
+ */
+export interface RealtimeInvalidationHint {
+    event: string;
+    entity: string;
+    id?: string;
+}
+/**
+ * Maps a hint to the React Query keys that should be invalidated. Receiving a
+ * `{ entity: "booking", id }` hint typically invalidates both the list and the
+ * detail key for that entity.
+ */
+export type HintToQueryKeys = (hint: RealtimeInvalidationHint) => ReadonlyArray<QueryKey>;
+/**
+ * Pure translation of a channel message into the query keys to invalidate.
+ * Returns `[]` when the payload is not a recognisable hint or the map yields
+ * nothing — callers can safely spread the result into `invalidateQueries`.
+ */
+export declare function resolveInvalidationKeys(message: RealtimeClientMessage, map: HintToQueryKeys): ReadonlyArray<QueryKey>;
+//# sourceMappingURL=query-keys.d.ts.map

package/dist/query-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-keys.d.ts","sourceRoot":"","sources":["../src/query-keys.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AAErD,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAE3D;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,EAAE,CAAC,EAAE,MAAM,CAAA;CACZ;AAED;;;;GAIG;AACH,MAAM,MAAM,eAAe,GAAG,CAAC,IAAI,EAAE,wBAAwB,KAAK,aAAa,CAAC,QAAQ,CAAC,CAAA;AAWzF;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,qBAAqB,EAC9B,GAAG,EAAE,eAAe,GACnB,aAAa,CAAC,QAAQ,CAAC,CAGzB"}

package/dist/query-keys.js

@@ -0,0 +1,16 @@
+function isHint(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        typeof value.entity === "string" &&
+        typeof value.event === "string");
+}
+/**
+ * Pure translation of a channel message into the query keys to invalidate.
+ * Returns `[]` when the payload is not a recognisable hint or the map yields
+ * nothing — callers can safely spread the result into `invalidateQueries`.
+ */
+export function resolveInvalidationKeys(message, map) {
+    if (!isHint(message.data))
+        return [];
+    return map(message.data);
+}

package/dist/use-channel.d.ts

@@ -0,0 +1,21 @@
+import type { PresenceMember, RealtimeClientMessage } from "./connector.js";
+export interface UseChannelOptions {
+    /** Called for each message delivered on the channel. */
+    onMessage?: (message: RealtimeClientMessage) => void;
+    /** Called when the channel's presence set changes. */
+    onPresence?: (members: ReadonlyArray<PresenceMember>) => void;
+    /** Resume marker for replay-capable vendors. */
+    sinceId?: string;
+    /** Local presence profile announced to the channel. */
+    profile?: unknown;
+    /** Set `false` to pause the subscription without unmounting. */
+    enabled?: boolean;
+}
+/**
+ * Subscribe to a single realtime channel. Mints a token via the provider's
+ * token route, opens a connection through the injected connector, and tears it
+ * down on unmount / channel change. Vendor-agnostic — the transport is whatever
+ * connector the `RealtimeReactProvider` was given.
+ */
+export declare function useChannel(channel: string | null | undefined, options?: UseChannelOptions): void;
+//# sourceMappingURL=use-channel.d.ts.map

package/dist/use-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-channel.d.ts","sourceRoot":"","sources":["../src/use-channel.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAG3E,MAAM,WAAW,iBAAiB;IAChC,wDAAwD;IACxD,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;IACpD,sDAAsD;IACtD,UAAU,CAAC,EAAE,CAAC,OAAO,EAAE,aAAa,CAAC,cAAc,CAAC,KAAK,IAAI,CAAA;IAC7D,gDAAgD;IAChD,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,uDAAuD;IACvD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,gEAAgE;IAChE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,OAAO,GAAE,iBAAsB,QA8B7F"}

package/dist/use-channel.js

@@ -0,0 +1,38 @@
+"use client";
+import { useEffect, useRef } from "react";
+import { useRealtimeContext } from "./provider.js";
+/**
+ * Subscribe to a single realtime channel. Mints a token via the provider's
+ * token route, opens a connection through the injected connector, and tears it
+ * down on unmount / channel change. Vendor-agnostic — the transport is whatever
+ * connector the `RealtimeReactProvider` was given.
+ */
+export function useChannel(channel, options = {}) {
+    const { connector, fetchToken } = useRealtimeContext();
+    const { onMessage, onPresence, sinceId, profile, enabled = true } = options;
+    // Keep the latest callbacks without re-subscribing on every render.
+    const handlers = useRef({ onMessage, onPresence });
+    handlers.current = { onMessage, onPresence };
+    useEffect(() => {
+        if (!channel || !enabled)
+            return;
+        let connection = null;
+        let cancelled = false;
+        void fetchToken().then(({ token }) => {
+            if (cancelled)
+                return;
+            connection = connector.subscribe({
+                channel,
+                token,
+                sinceId,
+                profile,
+                onMessage: (message) => handlers.current.onMessage?.(message),
+                onPresence: (members) => handlers.current.onPresence?.(members),
+            });
+        });
+        return () => {
+            cancelled = true;
+            connection?.unsubscribe();
+        };
+    }, [channel, enabled, sinceId, profile, connector, fetchToken]);
+}

package/dist/use-live-queries.d.ts

@@ -0,0 +1,19 @@
+import type { RealtimeClientMessage } from "./connector.js";
+import { type HintToQueryKeys } from "./query-keys.js";
+export interface UseLiveQueriesOptions {
+    /** Pause all subscriptions without unmounting. */
+    enabled?: boolean;
+    /** Observe raw messages in addition to the invalidation behaviour. */
+    onMessage?: (channel: string, message: RealtimeClientMessage) => void;
+}
+/**
+ * The hook most screens need: subscribe to one or more channels and translate
+ * each invalidation hint into `queryClient.invalidateQueries` calls, so
+ * existing data-fetching screens go live without rewriting their data layer.
+ *
+ * `map` turns a hint (`{ entity, id }`) into the React Query keys to refetch.
+ * Subscriptions are managed by a single effect (no hooks-in-a-loop); pass a
+ * stable `channels` array (memoise in the caller) to avoid re-subscribing.
+ */
+export declare function useLiveQueries(channels: ReadonlyArray<string>, map: HintToQueryKeys, options?: UseLiveQueriesOptions): void;
+//# sourceMappingURL=use-live-queries.d.ts.map

package/dist/use-live-queries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-live-queries.d.ts","sourceRoot":"","sources":["../src/use-live-queries.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,qBAAqB,EAAsB,MAAM,gBAAgB,CAAA;AAE/E,OAAO,EAAE,KAAK,eAAe,EAA2B,MAAM,iBAAiB,CAAA;AAE/E,MAAM,WAAW,qBAAqB;IACpC,kDAAkD;IAClD,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACtE;AAED;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,EAC/B,GAAG,EAAE,eAAe,EACpB,OAAO,GAAE,qBAA0B,QA8CpC"}

package/dist/use-presence.d.ts

@@ -0,0 +1,7 @@
+import type { PresenceMember } from "./connector.js";
+/**
+ * Track the presence member list of a channel ("Ana is viewing this booking").
+ * Returns the current members; `profile` is announced as this client's entry.
+ */
+export declare function usePresence(channel: string | null | undefined, profile?: unknown): ReadonlyArray<PresenceMember>;
+//# sourceMappingURL=use-presence.d.ts.map

package/dist/use-presence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-presence.d.ts","sourceRoot":"","sources":["../src/use-presence.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAA;AAGpD;;;GAGG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EAClC,OAAO,CAAC,EAAE,OAAO,GAChB,aAAa,CAAC,cAAc,CAAC,CAM/B"}

package/dist/use-presence.js

@@ -0,0 +1,12 @@
+"use client";
+import { useState } from "react";
+import { useChannel } from "./use-channel.js";
+/**
+ * Track the presence member list of a channel ("Ana is viewing this booking").
+ * Returns the current members; `profile` is announced as this client's entry.
+ */
+export function usePresence(channel, profile) {
+    const [members, setMembers] = useState([]);
+    useChannel(channel, { profile, onPresence: setMembers });
+    return members;
+}

package/package.json

@@ -0,0 +1,77 @@
+{
+  "name": "@voyant-travel/realtime-react",
+  "version": "0.1.0",
+  "license": "Apache-2.0",
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": "./src/index.ts",
+    "./provider": "./src/provider.tsx",
+    "./connector": "./src/connector.ts",
+    "./connector-cloud": "./src/connector-cloud.ts",
+    "./query-keys": "./src/query-keys.ts"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check src/",
+    "test": "vitest run --passWithNoTests",
+    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "prepack": "pnpm run build"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^19.0.0"
+  },
+  "devDependencies": {
+    "@tanstack/react-query": "^5.100.11",
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^19.2.14",
+    "@voyant-travel/voyant-typescript-config": "workspace:^",
+    "jsdom": "^25.0.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^6.0.2",
+    "vitest": "^4.1.2"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "import": "./dist/index.js",
+        "default": "./dist/index.js"
+      },
+      "./provider": {
+        "types": "./dist/provider.d.ts",
+        "import": "./dist/provider.js",
+        "default": "./dist/provider.js"
+      },
+      "./connector": {
+        "types": "./dist/connector.d.ts",
+        "import": "./dist/connector.js",
+        "default": "./dist/connector.js"
+      },
+      "./connector-cloud": {
+        "types": "./dist/connector-cloud.d.ts",
+        "import": "./dist/connector-cloud.js",
+        "default": "./dist/connector-cloud.js"
+      },
+      "./query-keys": {
+        "types": "./dist/query-keys.d.ts",
+        "import": "./dist/query-keys.js",
+        "default": "./dist/query-keys.js"
+      }
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/voyant-travel/voyant.git",
+    "directory": "packages/realtime-react"
+  }
+}