@belonguniverseai/react-sdk 0.6.27 → 0.6.29

package/README.md

@@ -27,6 +27,7 @@ export function App() {
         return await getBelongToken();
       }}
       backend="https://your-belong-backend.example.com"
+      tenant="your-tenant-id-or-slug"
     />
   );
 }
@@ -38,6 +39,7 @@ export function App() {
 | ---------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `getToken`       | `() => Promise<string>`                                                   | yes      | Resolves a bearer token per request (DI auth; never cached).                                                                                         |
 | `backend`        | `string`                                                                  | yes      | Belong backend base URL.                                                                                                                             |
+| `tenant`         | `string`                                                                  | no       | Public tenant ID or slug for branding. Required when the API hosts multiple tenants; omit on a single-tenant API. Auth still comes from the JWT.     |
 | `universeOrigin` | `string`                                                                  | no       | **Deprecated, ignored.** Cross-origin navigation keys off `window.location`; safe to remove.                                                         |
 | `agentId`        | `string`                                                                  | no       | Sent as `X-Belong-Agent-Id` on every request.                                                                                                        |
 | `locale`         | `BelongLocale`                                                            | no       | Host/tenant default language (user choice still wins).                                                                                               |
@@ -48,15 +50,42 @@ export function App() {
 The dock renders into its own shadow root, so its styles never leak into (or
 inherit from) your app.
 
+### Tenant default theme
+
+Both the React component and `window.belong.init({ apiBaseUrl, tenant })` load
+`GET /v1/config/theme?tenant=<id-or-slug>` before rendering the dock. The API
+resolves the active tenant and reads `tenants/<tenantId>/config/theme.json` from
+its private asset store, with the existing knowledge-domain theme as a fallback.
+The browser needs no bucket credentials or direct bucket access.
+
+The published tenant theme is the default. Appearance settings offer **Company
+default**, **Belong**, **Simetrik**, and **Custom**. Explicit style choices are
+stored per API endpoint and tenant. Selecting Company default restores the latest
+published branding; old unscoped style preferences cannot silently replace it.
+The SDK refreshes the baseline on page focus or when the tab becomes visible,
+while preserving an explicit style and personal color-mode/position preferences.
+The script embed can also restore it with `belong.applyPreset("tenant")`.
+
+Theme reads bypass HTTP caches. API instances refresh their tenant registry and
+asset cache using the existing `assets_revision` signal, so publishing must
+advance that revision. A first read also syncs revision-0 tenants added after boot.
+Network failures retain the last good theme or built-in/inline fallback; initial
+theme reads time out after five seconds so an unavailable API cannot block the dock.
+
+Rollout requires releasing the API and both SDK bundles, then upgrading the SDK
+installed in each host application. No admin-page change or public bucket access
+is required. Configure each deployment with the intended environment/region's
+tenant bucket and backend read permissions.
+
 ### Host context (`window.belong.init`)
 
 The script-tag embed's `init` takes two optional host-context props that
 personalise what the dock shows before the first message:
 
-| Prop          | Type                                              | Required | Description                                                         |
-| ------------- | ------------------------------------------------- | -------- | ------------------------------------------------------------------- |
-| `user`        | `{ displayName?: string }`                        | no       | Signed-in user; personalises the first message and the avatar menu. |
-| `pageContext` | `{ label?: string; fromDocumentTitle?: boolean }` | no       | Page label for the first message; defaults to the tab title.        |
+| Prop          | Type                                              | Required | Description                                                                         |
+| ------------- | ------------------------------------------------- | -------- | ----------------------------------------------------------------------------------- |
+| `user`        | `{ displayName?: string }`                        | no       | Signed-in user; personalises the first message and the avatar menu.                 |
+| `pageContext` | `{ label?: string; fromDocumentTitle?: boolean }` | no       | Page label shown in the dock and sent with each message; defaults to the tab title. |
 
 Both have runtime setters on `window.belong`, alongside `setLocale` and
 `setWorkspace`:
@@ -69,6 +98,16 @@ Both have runtime setters on `window.belong`, alongside `setLocale` and
   dock reads `document.title` live (SPA navigation updates it), unless the host
   passed `pageContext: { fromDocumentTitle: false }`.
 
+The page label is also **sent with every message**, so the agent can resolve
+"this page": the label the composer's page chip shows at send time (host label,
+`init` label, or the tab title) rides the message, and the agent reads it as
+host-reported context, never as something the user typed. Only the label is
+sent, never the page's contents, and it is stored with the message like the
+message text. A tab title can carry customer names, record ids or the
+signed-in user's email: if yours does, give the dock a clean label with
+`setPageContext(label)`, or pass `pageContext: { fromDocumentTitle: false }` so
+nothing is sent unless you set one.
+
 A re-`init` states the host's context in full: omitting `user` or
 `pageContext` CLEARS what a previous `init` seeded (the config is replaced
 wholesale, not merged). A live `setUser` / `setPageContext` override outranks

package/dist/api/account-scope.d.ts

@@ -0,0 +1,75 @@
+import { QueryClient } from '@tanstack/react-query';
+/**
+ * The stable identity of the account speaking to `apiBaseUrl` right now. An
+ * opaque string — callers put it in a query key and compare it, never parse it.
+ */
+export declare const accountKey: (apiBaseUrl: string) => string;
+/** `accountKey`, re-read whenever the identity behind the auth source moves. */
+export declare const useAccountKey: () => string;
+/**
+ * Answers whether the account that BEGAN an action is still the active one, on
+ * the same backend. Call it immediately before the side effect, not once at the
+ * top of the callback: what matters is the instant the effect happens.
+ */
+export type StillInitiatingAccount = () => boolean;
+/**
+ * Bind an action to the account that starts it (P1, 2026-09-28 PR #614
+ * follow-up audit finding A).
+ *
+ * Partitioning the CACHE was only half the hole. Cancelling and dropping a
+ * previous account's READS does nothing to a MUTATION's promise callback: it is
+ * an ordinary `.then` on a promise nobody cancelled, it still holds the
+ * response the previous account's bearer authenticated, and unmounting does not
+ * stop it either. The audit reproduced the consequence — account A shares an
+ * unshared report, the host swaps to B in place while the response is in
+ * flight, and A's private bearer share url lands on B's CLIPBOARD.
+ *
+ * So every action captures the account it started under and re-asks before it
+ * does anything the world can see. The identity is the SAME `accountKey` the
+ * cache is partitioned by, deliberately and not for tidiness: a second notion
+ * of "who is this" is a second thing to get out of step, and that key already
+ * carries both axes the audit named — the token's stable CLAIMS and the BACKEND
+ * (`apiBaseUrl`) they speak to, which is the "backend generation" half.
+ *
+ * It cannot rotate spuriously for a token whose claims are readable, which is
+ * every production shape: the key is derived from `tenant_id`+`user_id` (or
+ * `iss`+`sub`), so a token REFRESH of the same session produces the same key and
+ * the action completes normally. The one identity that does re-key on a refresh
+ * is an OPAQUE token, which falls back to the unreadable-identity epoch; there
+ * the cost
+ * is only that the automatic clipboard hand-off is skipped — the link was still
+ * minted, and the card's own copy control is right there — which is the safe
+ * direction of that trade and the same one the cache partition already takes.
+ */
+export declare const useAccountBinding: () => (() => StillInitiatingAccount);
+/**
+ * Cancel and drop every account-scoped read that does not belong to whoever is
+ * speaking to `apiBaseUrl` RIGHT NOW.
+ *
+ * The key is derived inside the predicate, on every evaluation, and that is
+ * load-bearing rather than tidy: this function awaits `cancelQueries`, and the
+ * account can change across that await — a component-embed mount does exactly
+ * that, moving off the pending partition as soon as the getter answers. A
+ * captured key then deletes the NEW account's freshly created read as "another
+ * account's", and the surface is left with no query at all: a reports list that
+ * silently never loads. Asking again at removal time cannot get that wrong.
+ */
+export declare const dropOtherAccountReads: (queryClient: QueryClient, apiBaseUrl: string) => Promise<void>;
+/**
+ * Cancel and drop EVERY cached read except the deployment probes.
+ *
+ * For a logout, not for an account switch. Most of the dock's reads are
+ * caller-scoped without being account-KEYED — connectors, sessions, workspace
+ * files, saved prompts — and enumerating them here would mean guessing at each
+ * feature's invalidation semantics. A logout needs no such guess: nothing
+ * cached belongs to nobody, so all of it goes, and whatever the next sign-in
+ * needs it re-reads. The probes stay because they describe the deployment.
+ */
+export declare const dropEveryCallerScopedRead: (queryClient: QueryClient) => Promise<void>;
+/**
+ * Keep the cache partitioned by account for the whole SDK lifetime. Mount ONCE
+ * at the root (`SdkProviders`), not in a surface: a logout unmounts every view,
+ * so a purge that lived in one of them would never run for the one transition
+ * where leaving the rows behind matters most.
+ */
+export declare const useAccountCachePartition: () => void;

package/dist/api/artifact-actions.d.ts

@@ -24,6 +24,5 @@ export type ArtifactActionApi = {
 };
 /** What the report bridge may call: everything except the parent-only stop control. */
 export type ArtifactBridgeApi = Omit<ArtifactActionApi, "settle">;
-export declare const ARTIFACT_API_REQUEST_TIMEOUT_MS = 20000;
 /** Parent-only authenticated adapter. Generated HTML cannot select the target or auth source. */
 export declare const createArtifactActionApi: (apiBaseUrl: string, artifactId: string, workspaceExternalId: string | null) => ArtifactActionApi;

package/dist/api/auth-errors.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The dock's "the host session is gone" error. A leaf module so the request
+ * layer (client.ts), the chat transport and the chat route share one prefix
+ * without importing each other.
+ */
+/**
+ * The prefix the dock recognizes as "the host session is gone" — the chat
+ * renders `chat.authExpired` with a Retry for any error that starts with it.
+ */
+export declare const AUTH_EXPIRED_ERROR_PREFIX = "auth_expired:";
+/**
+ * Raised INSTEAD of sending an authenticated request when the registered auth
+ * source yields no usable token, even after one forced refresh and a bounded
+ * wait. A header-less request can only 401 (`missing_authorization_header`)
+ * and, from a long-lived loop, it never stops — prod 2026-10-15 saw 1,246 of
+ * them. Failing locally keeps the backend quiet and gives the dock a
+ * recognizable signed-out error (the `auth_expired:` prefix).
+ */
+export declare class BelongAuthUnavailableError extends Error {
+    constructor();
+}

package/dist/api/client-identity.d.ts

@@ -6,7 +6,9 @@ declare const jwtIdentitySchema: z.ZodObject<{
     iss: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export type ClientIdentity = z.infer<typeof jwtIdentitySchema>;
-/** Notified when the async getter's identity becomes known or is reset. */
+/** Generation of the current effective token, when its claims cannot be read. */
+export declare const readUnreadableIdentityEpoch: () => number;
+/** Notified when the identity behind the SDK's auth source may have changed. */
 export declare const subscribeClientIdentity: (listener: () => void) => (() => void);
 export declare const readClientIdentity: () => ClientIdentity | null;
 export {};