Super Livekit Web Package

super-livekit bundles everything you need to trigger and monitor Livekit video calls from a web UI. Initialize it once, drop in the ready-made CallButton, or compose your own experience with the exposed hooks, REST helpers, and native bridge integrations.

Highlights

• Single initialization for REST + Centrifuge endpoints, auth token resolution, and copy overrides.
• Embeddable CallButton component that handles call setup, timeouts, and lifecycle events.
• Headless hooks for custom UIs: call control, mobile bridge wiring, and WebApp listeners.
• HTTP utilities to fetch users and call history via your REST backend.
• Mobile-friendly: opt-in bridge callbacks and window.webAppListener support for hybrid apps.

Installation

npm install super-livekit
# or
yarn add super-livekit

Quick Start

import { initialize } from "super-livekit";

initialize({
  restApiBaseUrl: process.env.LIVEKIT_REST!, // e.g. https://api.example.com
  centrifugeUrl: process.env.LIVEKIT_WS!, // e.g. wss://ws.example.com/connection/websocket
  getAccessToken: () => window.sessionStorage.getItem("access_token") ?? undefined,
  notify: (message, status) => console.log(status, message),
  copy: {
    callButtonLabel: "Call video",
  },
});

Drop the button anywhere in your React tree:

import { CallButton } from "super-livekit";

function ContactActions({ userId }: { userId: string }) {
  return <CallButton calleeId={userId} />;
}

When pressed, the button calls your /calls/make endpoint, connects to the Centrifuge channel, tracks status transitions, and notifies any configured native bridges.

Configuration Reference

initialize(config: SuperLivekitConfig) accepts:

| Option | Type | Description | | ---------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------------- | | restApiBaseUrl | string | Required REST base URL (trailing slash optional). | | centrifugeUrl | string | Required Centrifuge WebSocket URL. | | getAccessToken | string \| () => string \| Promise<string \| undefined> | Optional bearer token resolver used for REST + Centrifuge connections. | | logger | Pick<Console, "log" \| "warn" \| "error"> | Override logging output. Defaults to console. | | notify | (message: string, status: "success" \| "failed" \| "info") => void | Optional notification hook surfaced throughout the library. | | mobileBridge | MobileBridge | Pre-register a native bridge implementation (Flutter, RN, etc.). | | copy | CopyOverrides | Provide translated/overridden UI strings such as the call button label. |

Helpers:

• getInitializeState() → { initialized: boolean }
• subscribeInitializeState(listener) → unsubscribe function
• getCopy() → active copy overrides

UI Component

<CallButton />

<CallButton
  calleeId="user-123"
  type="video" // defaults to "video"
  label="Video Call" // override global copy
  mobileBridge={customBridge}
  onStatusChange={(status) => console.log("call status", status)}
  onCallStart={(detail) => console.log("connection detail", detail)}
  onError={(error) => toast.error(error.message)}
/>

Need a custom control? Provide a render prop:

<CallButton
  calleeId={userId}
  render={({ onClick, isCalling }) => (
    <PrimaryButton loading={isCalling} onClick={onClick}>
      Call video
    </PrimaryButton>
  )}
/>

The button exposes disabled/loading states while requests are in flight and cleans up subscriptions when calls end or timeout.

Hooks & Clients

useCallController(options)

Headless control over the call lifecycle. Returns:

const {
  callId,
  callStatus,
  connectionDetail,
  isMakingCall,
  makeCallError,
  currentCallRequest,
  initiateCall,
  connectToCallChannel,
  cancelCall,
  missedCall, // Call this when UI timeout expires
  endCall,
  resetCall,
} = useCallController({
  onStatusChange: (status) => console.log(status),
  onCentrifugeEvent: (event, data) => console.log(event, data),
  mobileBridge: customBridge,
});

Key methods:

• initiateCall(request) – Start a call. Returns connection details.
• missedCall() – Mark current call as missed (e.g., when your UI timer expires). Backend will send a Centrifuge event to update UI state.
• cancelCall() – Cancel the current call.
• endCall() – End an active call.
• resetCall() – Reset all call state.

Example: Custom timeout handling

function CustomCallUI({ calleeId }: { calleeId: string }) {
  const { initiateCall, missedCall, callStatus } = useCallController();

  useEffect(() => {
    if (callStatus === "waiting") {
      const timer = setTimeout(() => {
        missedCall(); // Mark as missed after 30s
      }, 30000);

      return () => clearTimeout(timer);
    }
  }, [callStatus, missedCall]);

  return <button onClick={() => initiateCall({ calleeId, type: "video" })}>Call {calleeId}</button>;
}

Other Hooks

• useMobileAppConnection(options) – listen for window.webAppListener events (onAcceptedCall, onEndCall, etc.) and react inside React components.
• useMobileMethodHandler({ bridge }) – interact with registered native bridge methods (e.g. acceptedToJoinCall, endedCall).
• useWebAppListener(handler) – lightweight helper for attaching a single listener to window.webAppListener.
• createVideoCallClient() – factory that yields a plain client with makeCall, markCallMissed, and connect methods for use outside React.

REST Helpers

Use the built-in HTTP helpers when you need to make related REST calls from your integration. They automatically reuse configuration, auth headers, and error handling.

import {
  getUsersRequest,
  getCallHistoryRequest,
  type GetUsersRequest,
  type GetCallHistoryRequest,
} from "super-livekit";

const users = await getUsersRequest({ limit: 10, page: 1, q: "jane" });
const history = await getCallHistoryRequest({ limit: 5, status: "completed" });

• getUsersRequest(params?: GetUsersRequest) → { users, pagination }
• getCallHistoryRequest(params?: GetCallHistoryRequest) → { calls, pagination }

Both helpers expect your backend to respond with { code: 0, data: ... }.

Mobile & Hybrid Integration

``32 If your host app posts events into the web view via window.webAppListener(eventName, payload), the hooks and CallButton respond automatically:

• onAcceptedCall { callId } → connects to the Centrifuge channel and resolves connectionDetail.
• onEndCall { reason? } → ends the active call and performs cleanup.

Bridge callbacks (mobileBridge.acceptedToJoinCall, mobileBridge.endedCall) receive JSON strings of the relevant payload, allowing native shells to stay in sync.

Types

The package re-exports key types so you can annotate your code:

• CallStatus, ConnectionDetail, MakeCallRequest
• GetUsersRequest, GetUsersResponse, UserListItem, UsersPagination
• GetCallHistoryRequest, GetCallHistoryResponse, CallHistoryItem
• CentrifugeData, EventName, CentrifugeEventName

Check src/index.ts for the complete export map.

Development

npm run build        # compile to dist/ (ESM, CJS, and .d.ts)
npm run lint         # optional lint task if configured in your project
npm publish          # remember to bump version beforehand

License

MIT © Teknix