@robono/web
v0.6.1
Published
Headless Robono SDK for browser applications.
Maintainers
Readme
@robono/web
Headless Web SDK for Robono Bridge. It uses your product's existing login, screens, storage, and notifications, synchronizes after realtime or push events, retains polling as recovery, and pauses polling while the page is hidden.
License
Licensed for authorized Robono integrations. Redistribution as a standalone SDK, bypassing Robono, and competing bridge services are prohibited. See the included LICENSE and license FAQ.
Install
The package is ESM-only. CommonJS build tooling must load it with
await import("@robono/web").
npm install @robono/webThe package includes TypeScript declarations and SBOM.spdx.json.
Start
import { createRobonoWeb } from "@robono/web";
const bridge = createRobonoWeb({
externalUserId: signedInUser.id,
http: {
baseUrl: window.location.origin,
getAccessToken: () => yourAuth.getAccessToken(),
language: signedInUser.language,
},
});
const unsubscribe = bridge.client.subscribe(
renderWithYourExistingScreens,
);
try {
await bridge.start();
} catch (error) {
// Initial authentication, CORS, and configuration failures reject.
showBridgeUnavailable(error);
}Use a BCP 47 value such as es. Localized, user-safe failures are available as
error.userMessage?.localized_message, and returned records may include
status_message.localized_message. After sign-in and whenever this participant
changes language, call bridge.client.preferences.updateLanguage(language).
The preference belongs to this connected app and signed-in participant, not to
a connection or guardian.
This preference localizes Robono-generated user notices; it does not translate
chat content or developer diagnostics.
Delayed events use stable code and parameters. Call
bridge.client.userMessages.localize({ code, parameters, language }) separately
for each viewer when child and guardian languages differ. Push or realtime
signals contain IDs only: synchronize first, then use fetched localized status
wording. Fallback is full locale, recognized script, base language, then English.
The subscribed state uses one connection and message shape for every endpoint returned by the directory. Use the unified connections.connect/list/update/disconnect and messages.send/list/mark methods without branching on endpoint type in your UI.
When a user ends a friendship, call connections.disconnect(...). For a disconnected connection, preserve history and remove sending, reply, and quote controls. Follow the connection lifecycle for changes initiated by either endpoint.
When your existing realtime or push layer receives a Robono event:
await bridge.receivePush(pushData);Push or realtime signals initiate immediate synchronization. Recovery polling runs about once a minute with jitter, backs off after failures, and pauses while the page is hidden. Call bridge.dispose() and unsubscribe() when the owning page ends. Subscribed state is temporary synchronization state, not your permanent database.
Never put a Robono API key in browser code. Your backend must mount the authenticated and authorized /robono/* route supplied by @robono/server.
For a separate backend origin, allow only your exact website origin, handle OPTIONS, and permit the authentication headers your app uses plus Accept-Language. Do not combine credentials with a wildcard origin.
This is an early-access 0.x package. Patch releases are compatible fixes; a
minor release before 1.0 may contain a documented breaking change. Each minor
line receives critical security and Bridge compatibility fixes for at least 12
months after its successor is published. Read the packaged CHANGELOG.md before upgrading and
report SDK problems at
robono.com/contact?topic=sdk.
Full documentation is at robono.com/docs.
