@belonguniverseai/react-sdk 0.6.17 → 0.6.19

package/README.md

@@ -34,18 +34,80 @@ export function App() {
 
 ### Props
 
-| Prop             | Type                    | Required | Description                                                                                  |
-| ---------------- | ----------------------- | -------- | -------------------------------------------------------------------------------------------- |
-| `getToken`       | `() => Promise<string>` | yes      | Resolves a bearer token per request (DI auth; never cached).                                 |
-| `backend`        | `string`                | yes      | Belong backend base URL.                                                                     |
-| `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).                                       |
-| `panelEnabled`   | `boolean`               | no       | Whether the active workspace shows the assistant panel.                                      |
+| Prop             | Type                                                                      | Required | Description                                                                                                                                          |
+| ---------------- | ------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `getToken`       | `() => Promise<string>`                                                   | yes      | Resolves a bearer token per request (DI auth; never cached).                                                                                         |
+| `backend`        | `string`                                                                  | yes      | Belong backend base URL.                                                                                                                             |
+| `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).                                                                                               |
+| `panelEnabled`   | `boolean`                                                                 | no       | Whether the active workspace shows the assistant panel.                                                                                              |
+| `agentGrant`     | `{ provider?: string; scopeExternalId?: string; scopeUrlParam?: string }` | no       | Optional CLI agent-grant overrides. Most hosts need none of this — a scoped `workspace` already offers the default grant.                            |
+| `workspace`      | `string \| null`                                                          | no       | Active workspace id — re-scopes sessions, files, chat, and the CLI grant on switch. `null` disables scoped surfaces while resolving; omit if unused. |
 
 The dock renders into its own shadow root, so its styles never leak into (or
 inherit from) your app.
 
+### 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.        |
+
+Both have runtime setters on `window.belong`, alongside `setLocale` and
+`setWorkspace`:
+
+- `belong.setUser({ displayName })` — wins over `init({ user })`. `setUser(null)`
+  drops the override back to the init value; `setUser({ displayName: null })`
+  means "no name for this user" and shows none even when `init` seeded one.
+- `belong.setPageContext(label)` — wins over `init({ pageContext })` and the tab
+  title; `setPageContext(null)` drops the override. With no label anywhere, the
+  dock reads `document.title` live (SPA navigation updates it), unless the host
+  passed `pageContext: { fromDocumentTitle: false }`.
+
+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
+`init` and survives a later one — clear it with `null` to hand control back to
+the init values.
+
+Neither value is persisted — a reload re-derives both from the host's next
+`init`.
+
+## Account authorization and Content Security Policy
+
+Browser-bound account authorization opens an `about:blank` popup, clears its
+`opener`, and submits a form POST to the configured API's `browserBindingUrl`.
+The popup inherits the embedding document's CSP even after its opener is cleared.
+If that document restricts `form-action`, allow both the API bootstrap origin and
+the authorization provider's origin in every enforced policy. Chromium also checks
+the bootstrap's 303 redirect against this policy; allowing only the API is not enough.
+
+For example, a deployment using the public Microsoft login service could use:
+
+```http
+Content-Security-Policy: form-action 'self' https://your-belong-backend.example.com https://login.microsoftonline.com
+```
+
+Merge those hosts into your existing policy, using your actual API and configured
+provider origins (including any required redirect destinations). A same-origin API
+proxy is covered by `'self'`; the external provider still needs permission. Existing
+`connect-src` and API allowed-origin requirements continue to apply independently.
+
+An enforced `form-action` violation closes the popup and shows the existing
+authorization failure UI. Users can retry with the Connect/Reconnect action after
+the host policy is fixed. The SDK does not bypass CSP or offer direct provider
+navigation for bound responses. Proofs travel only in the POST body, never in URLs.
+The popup uses referrer policy `origin` so bootstrap POSTs retain a trustworthy
+`Origin` header; the backend redirect should send `Referrer-Policy: no-referrer`.
+
+Run the SDK's real Chromium checks (including cross-origin CSP and manual fallback)
+from this package with `node --test tests/browser/authorization-popup.mjs`.
+
 ## Voice calls (new in 0.2.0)
 
 The dock's rail now carries a phone button: a real two-way **voice call** with a

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

@@ -30,9 +30,9 @@ declare const accountConnectorSchema: z.ZodObject<{
             disconnect: "disconnect";
         }>;
         label: z.ZodEnum<{
+            reconnect: "reconnect";
             disconnect: "disconnect";
             connect: "connect";
-            reconnect: "reconnect";
             grant_admin_consent: "grant_admin_consent";
         }>;
         tone: z.ZodEnum<{
@@ -43,15 +43,21 @@ declare const accountConnectorSchema: z.ZodObject<{
         requiresConfirmation: z.ZodBoolean;
     }, z.core.$strip>>;
 }, z.core.$strip>;
-declare const accountConnectorActionResultSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    kind: z.ZodLiteral<"authorization">;
-    authorizationUrl: z.ZodURL;
-    completion: z.ZodLiteral<"action_unavailable">;
-}, z.core.$strip>, z.ZodObject<{
-    kind: z.ZodLiteral<"completed">;
-}, z.core.$strip>], "kind">;
 export type AccountConnector = z.infer<typeof accountConnectorSchema>;
-export type AccountConnectorActionResult = z.infer<typeof accountConnectorActionResultSchema>;
+export type AccountConnectorAuthorization = {
+    readonly kind: "authorization";
+    readonly authorizationUrl: string;
+    readonly completion: "action_unavailable";
+} & ({
+    readonly browserBindingUrl: string;
+    readonly browserProof: string;
+} | {
+    readonly browserBindingUrl?: never;
+    readonly browserProof?: never;
+});
+export type AccountConnectorActionResult = AccountConnectorAuthorization | {
+    readonly kind: "completed";
+};
 export type AccountConnectorListResult = {
     readonly status: "ready";
     readonly connectors: readonly AccountConnector[];
@@ -82,5 +88,8 @@ export type RunAccountConnectorActionResult = AccountConnectorActionResult | Acc
 export declare const listAccountConnectorsRequest: (api: ApiClient, signal?: AbortSignal) => Promise<AccountConnectorListResult>;
 export declare const runAccountConnectorActionRequest: (api: ApiClient, input: RunAccountConnectorActionInput) => Promise<RunAccountConnectorActionResult>;
 export declare const useAccountConnectors: () => import('@tanstack/react-query').UseQueryResult<NoInfer<AccountConnectorListResult>, Error>;
-export declare const useRunAccountConnectorAction: () => import('@tanstack/react-query').UseMutationResult<RunAccountConnectorActionResult, Error, RunAccountConnectorActionInput, unknown>;
+export declare const useRunAccountConnectorAction: () => {
+    mutateAsync: (input: RunAccountConnectorActionInput) => Promise<RunAccountConnectorActionResult>;
+    isPending: boolean;
+};
 export {};