@belonguniverseai/react-sdk 0.6.21 → 0.6.23

package/README.md

@@ -78,6 +78,75 @@ the init values.
 Neither value is persisted — a reload re-derives both from the host's next
 `init`.
 
+### Opening the dock from the host (`window.belong.open`)
+
+`belong.open({ size?, draft? })` shows the chat view at the requested size:
+`"fullscreen"` covers the viewport on desktop (a phone resolves it to the open
+sheet, like the rail's own toggle), `"expanded"` docks it beside the page, and
+omitting `size` keeps the current size (a collapsed dock expands). `draft`
+prefills the composer — never sends it, only when the composer is empty, at
+most 4,000 characters — and focuses it. The user can always leave fullscreen.
+
+It is safe to call BEFORE `init` resolves: a request made before the dock
+mounts is applied at mount, so `open({ size: "fullscreen" })` followed by
+`init(...)` mounts straight into fullscreen with no flash of the docked size.
+
+### Host-bridged MCP (`init({ hostMcp })`)
+
+Some tools can only be reached from the signed-in user's own page — an MCP
+server behind an identity-aware proxy, an intranet, a cookie session. A tenant
+publishes such a server as an MCP plugin entry with `transport: "host"` and a
+same-origin `mcpUri` path (see `docs/guides/009-manual-agent-integration.md`);
+the agent's calls then travel to the dock, which POSTs each JSON-RPC
+`tools/call` to that path on the page's own origin with `credentials:
+"same-origin"` and relays the raw answer back.
+
+The host must opt in, per path:
+
+```js
+window.belong.init({
+  // …
+  hostMcp: { allowedPaths: ["/mcp"] }, // root-relative, exact match, at most 8
+});
+```
+
+A path not listed is refused in the page (`mcp_not_allowed`) whatever the
+tenant publishes; omitting `hostMcp` disables the feature. Requests carry
+`x-belong-source: dock` so the host can label its own audit logs; they follow no
+redirects (an expired proxy session reads as "sign-in expired", not as a login
+page), abort after 55 s, and relay at most 1,000,000 characters of body.
+
+### Restricting what the agent can do on the page (`init({ browserControl })`)
+
+By default the dock runs every browser-control op the agent sends: reading the
+page (`snapshot`, `read`), driving it (`click`, `type`, `select`, `press`,
+`navigate`), running JavaScript in it (`eval`) and host MCP calls (`mcp_call`).
+All of them act with the signed-in user's own session on your origin.
+
+A host can limit that to the ops it wants:
+
+```js
+window.belong.init({
+  // …
+  hostMcp: { allowedPaths: ["/mcp"] },
+  browserControl: { allowedOps: ["mcp_call"] }, // only the bridged MCP calls
+});
+```
+
+Every other op is refused in the page before it runs (`op_not_allowed`), and the
+agent is told the page does not allow it. `allowedOps: []` refuses everything.
+Omitting `browserControl` keeps every op, as before. A value that is present but
+invalid (an unknown op name, a misspelt key) refuses everything and logs a
+console warning, because a host that passed one meant to restrict the page. Like
+`hostMcp`, it is restated on every `init`.
+
+**If your page only bridges MCP, pass `allowedOps: ["mcp_call"]`.** Otherwise
+the agent can also script and click through the page with the viewer's session,
+which reaches everything `hostMcp.allowedPaths` was meant to fence off. That
+matters most when the agent reads text written by other people (customer
+conversations, tickets, email), since such text can carry instructions aimed at
+the agent.
+
 ## Account authorization and Content Security Policy
 
 Browser-bound account authorization opens an `about:blank` popup, clears its

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

@@ -19,8 +19,8 @@ declare const accountConnectorSchema: z.ZodObject<{
             error: "error";
             needs_auth: "needs_auth";
             ready: "ready";
-            needs_admin_consent: "needs_admin_consent";
             disabled: "disabled";
+            needs_admin_consent: "needs_admin_consent";
         }>;
     }, z.core.$strip>>;
     actions: z.ZodArray<z.ZodObject<{
@@ -31,8 +31,8 @@ declare const accountConnectorSchema: z.ZodObject<{
         }>;
         label: z.ZodEnum<{
             reconnect: "reconnect";
-            disconnect: "disconnect";
             connect: "connect";
+            disconnect: "disconnect";
             grant_admin_consent: "grant_admin_consent";
         }>;
         tone: z.ZodEnum<{

package/dist/api/api-keys.d.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { ApiClient } from './client.ts';
+declare const keyMetadataSchema: z.ZodObject<{
+    apiKeyId: z.ZodUUID;
+    name: z.ZodString;
+    createdAt: z.ZodISODateTime;
+}, z.core.$strip>;
+export type ApiKeyMetadata = z.infer<typeof keyMetadataSchema>;
+export declare const listApiKeys: (client: ApiClient) => Promise<readonly ApiKeyMetadata[]>;
+/** The creation secret is returned only to the caller; no React Query mutation stores it. */
+export declare const createApiKey: (client: ApiClient, name: string) => Promise<{
+    apiKeyId: string;
+    key: string;
+}>;
+export declare const revokeApiKey: (client: ApiClient, apiKeyId: string) => Promise<void>;
+export declare const useApiKeys: (ownerCacheKey: string) => import('@tanstack/react-query').UseQueryResult<NoInfer<readonly {
+    apiKeyId: string;
+    name: string;
+    createdAt: string;
+}[]>, Error>;
+export declare const useRevokeApiKey: (ownerCacheKey: string) => (apiKeyId: string) => Promise<void>;
+export {};

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

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+declare const jwtIdentitySchema: z.ZodObject<{
+    tenant_id: z.ZodOptional<z.ZodString>;
+    user_id: z.ZodOptional<z.ZodString>;
+    sub: z.ZodOptional<z.ZodString>;
+    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. */
+export declare const subscribeClientIdentity: (listener: () => void) => (() => void);
+export declare const readClientIdentity: () => ClientIdentity | null;
+export {};