Realtime

Most admin and customer screens can stay current without polling. Voyant ships a provider-agnostic realtime layer that pushes live updates to channels, and a React layer that turns those pushes into query invalidations. The platform never couples to a single transport vendor, and the whole feature is optional: a deployment with no provider configured stays inert. The backend lives in @voyant-travel/realtime. The React hooks live in @voyant-travel/realtime-react. This page covers both, plus how they relate to the managed Voyant realtime service.

The core idea: hints, not records

The realtime layer does not stream changed records over channels. It streams invalidation hints, small { event, entity, id } envelopes that say “this thing changed, refetch it.” The React layer reacts by invalidating matching React Query keys, which then refetch over the existing authenticated HTTP path. This design has three consequences worth understanding:

HTTP stays the source of truth. A channel never carries entity data, so it never leaks state through channel capabilities.
At-most-once delivery is acceptable. A missed hint self-heals on the next refetch or staleTime tick.
The transaction that emitted the event is never blocked by a publish.

If a channel ever needs at-least-once delivery, that is a durable channel-push pattern (write an intent row, drain it from a workflow), not this module. The realtime module ships the at-most-once tier by design.

The provider interface

The transport is injected through RealtimeProvider. Voyant is one implementation; any pub/sub backend (a hosted vendor, a self-hosted WebSocket or SSE service) can satisfy the same interface.

import type { RealtimeProvider } from "@voyant-travel/realtime/types"

interface RealtimeProvider {
  readonly name: string
  publish(channel: string, message: { event: string; data: unknown }): Promise<void>
  mintClientToken(input: {
    clientId: string
    capabilities: Record<string, ReadonlyArray<"subscribe" | "publish" | "presence">>
    ttlSeconds?: number
  }): Promise<{ token: string; expiresAt: string }>
}

mintClientToken is the abstraction line. Every vendor mints tokens differently, but the token-mint route never knows the vendor. The package ships two built-in providers:

Factory	Subpath	Backend
`createLocalRealtimeProvider()`	`@voyant-travel/realtime/providers/local`	in-memory, for dev and tests
`createVoyantCloudRealtimeProvider({ client })`	`@voyant-travel/realtime/providers/voyant-cloud`	Voyant transport

To bring your own backend, implement RealtimeProvider and pass it through. No framework change is required.

Wiring the module

@voyant-travel/realtime is part of the standard product graph. It owns no schema, is stateless, and contributes its runtime ports through the runtime entry in its voyant.package.v1 manifest, so the token-mint route and the deferred event bridge are resolved into the application rather than assembled by hand. What you do configure is the provider and the bridge routes that fan domain events out to channels:

import { createVoyantCloudRealtimeProvider } from "@voyant-travel/realtime/providers/voyant-cloud"

const realtime = {
  // Resolve the provider from runtime bindings.
  resolveProviders: (bindings) => [
    createVoyantCloudRealtimeProvider({ client: getCloudClient(bindings) }),
  ],

  // Fan domain events out to channels as invalidation hints.
  bridgeRoutes: {
    "booking.confirmed": (e) => ["admin", `booking:${e.bookingId}`],
    "booking.fully-paid": (e) => ({
      channels: ["admin", `booking:${e.bookingId}`],
      hint: { entity: "booking", id: e.bookingId },
    }),
    "availability.slot.changed": (e) => ({
      channels: ["admin", `product:${e.productId}`],
      hint: { entity: "availability", id: e.productId },
    }),
  },

  // Let portal customers subscribe to the bookings they own.
  resolvePortalScope: async (c) => {
    const personId = await lookupPersonId(c.get("db"), c.get("userId"))
    if (!personId) return null
    return { personId, bookingIds: await ownedBookingIds(c.get("db"), personId) }
  },
}

The token route is served on both surfaces, at POST /v1/admin/realtime/token and POST /v1/public/realtime/token. With no provider configured, the token route returns 503 and no bridge subscribers register.

The event bridge

bridgeRoutes is a declarative table from event name to channels and an optional hint. At bootstrap, the module registers one deferred event subscriber per route. Because the subscribers are deferred (inline: false), they run after the HTTP response via the runtime scheduler and never block the emitting transaction. Publish failures are swallowed and routed to onPublishError, because a dropped hint is self-healing. The module also exports the lower-level pieces: createRealtimeService, resolveRealtimeCapabilities, and the route helpers (createRealtimeRoutes, buildRealtimeRouteRuntime) for that path.

Channel conventions

Channels and the capabilities that grant them follow a stable convention.

Channel	Audience	Granted by
`admin`	all admin users of the deployment	admin session
`booking:{bookingId}`	admins and the booking’s customer	session plus ownership
`portal:customer:{personId}`	that customer in the portal	portal session
`notifications:user:{userId}`	a specific staff user	admin session

The operator pattern on the client

@voyant-travel/realtime-react makes existing screens live without rewriting their data layer. The transport is injected as a RealtimeConnector, so the React layer stays vendor-agnostic too. Wrap the app once. createRealtimeChannelConnector adapts the Voyant RealtimeChannel into a connector, but any vendor works by implementing RealtimeConnector directly.

import { RealtimeChannel } from "@voyant-travel/cloud-sdk"
import {
  createRealtimeChannelConnector,
  RealtimeReactProvider,
} from "@voyant-travel/realtime-react"

const connector = createRealtimeChannelConnector(RealtimeChannel, { baseUrl: "/api" })

<QueryClientProvider client={queryClient}>
  <RealtimeReactProvider connector={connector} tokenEndpoint="/v1/admin/realtime/token">
    <App />
  </RealtimeReactProvider>
</QueryClientProvider>

Then make a screen live with useLiveQueries. It subscribes to channels and translates each invalidation hint into queryClient.invalidateQueries calls. The operator pattern is exactly this: subscribe to the admin channel and map each hint’s entity to a query-key root.

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
}

Keep staleTime: 60_000 as a floor. A missed hint self-heals on the next stale tick, so a slow polling fallback remains a safe net under the hint-driven path. For finer control, the package also exports useChannel(channel, options) to subscribe to a single channel with auto token-mint, reconnect, and sinceId resume, and usePresence(channel, profile) for member lists (“Ana is viewing this booking”). Custom hint-to-key mapping is available through resolveInvalidationKeys and the HintToQueryKeys type from @voyant-travel/realtime-react/query-keys.

Framework realtime versus Cloud realtime

These are two layers, and they cooperate.

Framework realtime (@voyant-travel/realtime and @voyant-travel/realtime-react) is the deployment-side contract: the provider interface, the event bridge, the token-mint route, and the React hooks. It is vendor-agnostic.
Cloud realtime is the managed pub/sub transport: channels, presence, history, and RealtimeChannel. It is one implementation behind the provider interface, wired in through createVoyantCloudRealtimeProvider.

If you self-host a different backend, you keep the platform layer and swap the provider. If you use Voyant, the two snap together with no glue beyond the provider factory.

Next steps

Events

The fire-and-forget event bus the realtime bridge subscribes to.

Cloud realtime

The managed pub/sub transport behind the Voyant provider.

Caching

The HTTP path that hints invalidate, and its staleness model.

API routes

Where the token-mint route mounts and how surfaces are split.

Build on Voyant

Apps and extensions

Connectivity

Admin API

Storefront API

App API

The core idea: hints, not records

The provider interface

Wiring the module

The event bridge

Channel conventions

The operator pattern on the client

Framework realtime versus Cloud realtime

Next steps

Events

Cloud realtime

Caching

API routes

​The core idea: hints, not records

​The provider interface

​Wiring the module

​The event bridge

​Channel conventions

​The operator pattern on the client

​Framework realtime versus Cloud realtime

​Next steps

Events

Cloud realtime

Caching

API routes

The core idea: hints, not records

The provider interface

Wiring the module

The event bridge

Channel conventions

The operator pattern on the client

Framework realtime versus Cloud realtime

Next steps