@belonguniverseai/react-sdk 0.1.0

package/dist/types/public.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Public types the host embedding the SDK reads — keep this surface
+ * small and stable.
+ */
+export type BelongThemeMode = "light" | "dark";
+export type BelongThemeSide = "right" | "left";
+export type BelongThemeDensity = "comfortable" | "compact";
+/**
+ * One coherent colour palette. The theme carries both a light and a
+ * dark variant of this shape so toggling `mode` is a deterministic
+ * pick rather than a fragile colour-swap.
+ *
+ * Every value is CSS-legal (hex / rgb / hsl / `var(--…)`). Anna
+ * compiles tenant tokens into two `BelongThemePalette` objects.
+ */
+export type BelongThemePalette = {
+    readonly primary: string;
+    readonly primaryForeground: string;
+    readonly background: string;
+    readonly foreground: string;
+    readonly border: string;
+    readonly muted: string;
+    readonly mutedForeground: string;
+    readonly accent: string;
+    readonly accentForeground: string;
+    readonly destructive: string;
+    readonly destructiveForeground: string;
+    readonly userBubble: string;
+    readonly userBubbleForeground: string;
+    readonly assistantBubble: string;
+    readonly assistantBubbleForeground: string;
+};
+export type BelongThemeBrand = {
+    /** Friendly name shown in the dock header — "Belong", "Simetrik", … */
+    readonly name: string;
+    /** 1–2 letter avatar fallback. */
+    readonly initials: string;
+    /** Inline data-URL of the brand MARK (icon). Optional — `<BrandMark>` falls
+     *  back to the default Belong mark when absent. Validated at the perimeter. */
+    readonly logo?: string;
+};
+export type BelongTheme = {
+    readonly mode: BelongThemeMode;
+    readonly side: BelongThemeSide;
+    readonly density: BelongThemeDensity;
+    /** Pixel width of the expanded panel (the 44px collapsed strip is constant). */
+    readonly panelWidth: number;
+    readonly fontFamily: string;
+    /** CSS length, e.g. `"12px"` or `"0.75rem"`. Affects every shadcn radius. */
+    readonly radius: string;
+    readonly palettes: {
+        readonly light: BelongThemePalette;
+        readonly dark: BelongThemePalette;
+    };
+    readonly brand: BelongThemeBrand;
+    /** Optional accent override — recolours the active palette's brand/primary family. */
+    readonly accent?: string;
+    /** Custom CSS custom-property overrides, projected last so they win over theme vars. */
+    readonly cssVars?: Record<string, string>;
+};
+/**
+ * Deep-partial of `BelongTheme`. Every layer is optional so a caller
+ * can push just `palettes.light.primary` without restating the whole
+ * theme.
+ */
+export type PartialBelongTheme = {
+    readonly mode?: BelongThemeMode;
+    readonly side?: BelongThemeSide;
+    readonly density?: BelongThemeDensity;
+    readonly panelWidth?: number;
+    readonly fontFamily?: string;
+    readonly radius?: string;
+    readonly palettes?: {
+        readonly light?: Partial<BelongThemePalette>;
+        readonly dark?: Partial<BelongThemePalette>;
+    };
+    readonly brand?: Partial<BelongThemeBrand>;
+    /** Optional accent override — recolours the active palette's brand/primary family. */
+    readonly accent?: string;
+    /** Custom CSS custom-property overrides, projected last so they win over theme vars. */
+    readonly cssVars?: Record<string, string>;
+};
+/** Built-in theme presets selectable via `belong.applyPreset(name)`. */
+export type PresetName = "belong" | "simetrik" | "custom";
+/** Dock UI language. English is the default; Spanish is the localized option. */
+export type BelongLocale = "en" | "es";
+export type BelongInitInput = {
+    /** Belong cloud base URL, e.g. `https://api.belong.host` or `http://localhost:8787`. */
+    readonly apiBaseUrl: string;
+    /**
+     * Dock UI language for first-run + onboarding copy. Defaults to `"en"`; a
+     * Spanish-first tenant can pass `"es"`. The end user can still override it
+     * with the in-dock language toggle. (BEL-onboarding-i18n)
+     */
+    readonly locale?: BelongLocale;
+    /** Where to mount the dock. Defaults to `document.body`. */
+    readonly container?: HTMLElement | null;
+    /** Initial JWT — equivalent to calling `setToken(jwt)` immediately after `init`. */
+    readonly initialToken?: string;
+    /** Optional dev-time override: skip the dock chrome and mount the SPA inline. */
+    readonly mode?: "dock" | "inline";
+    /**
+     * Whether THIS workspace has a Belong panel. When `false`, the dock renders
+     * nothing — no rail, no panel, no reserved host margin — so workspaces that
+     * aren't configured with a panel don't show the assistant at all. Defaults to
+     * `true` (omitting it keeps the panel, preserving existing embeds). The host
+     * sets it per-workspace; on a SPA workspace switch, re-call `init` with the
+     * new value to flip it. (BEL-77)
+     */
+    readonly panelEnabled?: boolean;
+    /** Optional theme overrides applied at startup (before first render). */
+    readonly theme?: PartialBelongTheme;
+    /** Optional voice config (push-to-talk + read-aloud). */
+    readonly voice?: {
+        /** Hold-to-talk key as a `KeyboardEvent.code`. Default `"ControlLeft"`. */
+        readonly pushToTalkKey?: string;
+        /** Auto-read assistant replies aloud (ElevenLabs TTS). Default `true`. */
+        readonly autoplayTts?: boolean;
+        /** TTS voice id; omit/`""` to let the backend default apply. */
+        readonly voiceId?: string;
+        /** Flush a buffered partial utterance after this many ms. Default `1000`. */
+        readonly utteranceFlushMs?: number;
+        /** End a live call turn after this much trailing silence (ms). Default `3000`. */
+        readonly callSilenceMs?: number;
+        /** Client-side playback speed for spoken audio (pitch preserved). Default `0.9`; sane range 0.5–1.5. */
+        readonly ttsPlaybackRate?: number;
+        /** Minimum pause (ms) between spoken sentence chunks. Default `350`; `0` disables. */
+        readonly ttsChunkGapMs?: number;
+    };
+    /**
+     * Agent-grant (delegated CLI session) host context. When `scopeExternalId`
+     * is set — the host's active workspace id on the provider's side — the dock
+     * offers the consent card ("allow the agent to act on my behalf") and shows
+     * the session state. Omit it and the grant surface stays hidden.
+     */
+    readonly agentGrant?: {
+        /** Grant provider key. Defaults to `"simetrik"`. */
+        readonly provider?: string;
+        /** Provider-side scope (e.g. the Simetrik workspace id) the session binds to. */
+        readonly scopeExternalId?: string;
+        /**
+         * Track the scope LIVE from this page-URL search param (e.g. `"w"`,
+         * Simetrik's active-workspace param). When the host SPA switches
+         * workspace, the dock re-prompts consent for the new one — a grant is
+         * single-workspace, so each workspace needs its own. Takes precedence
+         * over a static `scopeExternalId` whenever the param is present.
+         */
+        readonly scopeUrlParam?: string;
+    };
+};
+export type RouteHandlerResult = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly error: string;
+};
+export type RouteHandler = (input: {
+    readonly routeName: string;
+    readonly params: Readonly<Record<string, string>>;
+}) => Promise<RouteHandlerResult>;
+export type UiActionResult<O> = {
+    readonly ok: true;
+    readonly output: O;
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+};
+export type UiActionHandler<I = unknown, O = unknown> = (input: I) => Promise<UiActionResult<O>>;
+export type BelongGlobal = {
+    readonly init: (input: BelongInitInput) => Promise<void>;
+    readonly setToken: (jwt: string) => void;
+    readonly setTheme: (theme: PartialBelongTheme) => void;
+    readonly applyPreset: (name: PresetName) => void;
+    readonly open: () => void;
+    readonly close: () => void;
+    readonly registerRouteHandler: (routeName: string, handler: RouteHandler) => void;
+    readonly registerUiAction: <I, O>(name: string, handler: UiActionHandler<I, O>) => void;
+    /** TEST-ONLY: inject a final voice transcript as if spoken. */
+    readonly __pushVoiceTranscript?: (text: string) => void;
+};
+declare global {
+    var belong: BelongGlobal | undefined;
+    interface Window {
+        belong?: BelongGlobal;
+    }
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@belonguniverseai/react-sdk",
+  "version": "0.1.0",
+  "description": "Belong — embeddable React AI assistant dock. Mount <BelongWidget> in your app tree with getToken dependency-injection auth.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "main": "./dist/component/index.js",
+  "module": "./dist/component/index.js",
+  "types": "./dist/component/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/component/index.d.ts",
+      "import": "./dist/component/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": [
+    "./dist/component/index.js"
+  ],
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "keywords": [
+    "belong",
+    "ai",
+    "assistant",
+    "react",
+    "widget",
+    "chat",
+    "agent"
+  ],
+  "publishConfig": {
+    "access": "public"
+  }
+}