@belonguniverseai/react-sdk 0.1.0

package/README.md

@@ -0,0 +1,47 @@
+# @belonguniverseai/react-sdk
+
+Embeddable **Belong** AI assistant dock as a React component. Mount `<BelongWidget>`
+inside your own React tree — no `<script>` tag, no globals. Authentication is
+dependency-injected via a `getToken` callback (called per request; Belong never
+caches your token).
+
+## Install
+
+```sh
+npm install @belonguniverseai/react-sdk
+```
+
+`react` and `react-dom` (>= 19) are peer dependencies — the component mounts on
+your app's single React copy.
+
+## Usage
+
+```tsx
+import { BelongWidget } from "@belonguniverseai/react-sdk";
+
+export function App() {
+  return (
+    <BelongWidget
+      getToken={async () => {
+        // Return a fresh Belong-audience JWT. Called per request.
+        return await getBelongToken();
+      }}
+      backend="https://your-belong-backend.example.com"
+    />
+  );
+}
+```
+
+### 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       | Canonical host origin for cross-origin navigation rebasing.        |
+| `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.            |
+
+The dock renders into its own shadow root, so its styles never leak into (or
+inherit from) your app.

package/dist/api/agent-grants.d.ts

@@ -0,0 +1,61 @@
+import { ApiClient } from './client.ts';
+export type AgentGrantStatusView = {
+    readonly status: "none";
+} | {
+    readonly status: "active" | "expired" | "revoked";
+    readonly grantId: string;
+    readonly provider: string;
+    readonly scopeExternalId: string;
+    readonly grantedAt: string | null;
+    readonly expiresAt: string | null;
+};
+export declare const useAgentGrantStatus: (input: {
+    readonly provider: string;
+    readonly scopeExternalId: string;
+} | null) => import('@tanstack/react-query').UseQueryResult<NoInfer<AgentGrantStatusView>, Error>;
+/**
+ * POST a grant create, with the connect self-heal. Two provider rejections
+ * recover the same way:
+ *
+ *   - 409 (anti-replay): the cached web JWT already minted a grant (e.g. on a
+ *     prior connect), so the provider refuses it.
+ *   - 429 (session cap): the workspace is at its concurrent-session limit. The
+ *     backend has just best-effort revoked-all the user's leaked sessions to
+ *     free a slot (§ agent-grant.service.ts), so a retry now fits under the cap.
+ *
+ * Either way: force-mint a brand-new token (`forceRotateBelongToken` →
+ * cacheMode:"off") and retry ONCE — the next request carries a JWT the provider
+ * has never seen, into a now-under-cap workspace. A no-op for non-Auth0 hosts
+ * (the retry re-sends the same token and fails identically, surfacing exactly
+ * as before). Standalone so the retry is unit-testable (mirrors
+ * `deleteSessionRequest`).
+ */
+export declare const createAgentGrantRequest: (api: ApiClient, input: {
+    readonly provider: string;
+    readonly scopeExternalId: string;
+}) => Promise<unknown>;
+/**
+ * BEL-79 fail-fast beacon: tell the backend a reactive reconnect has FAILED for
+ * good (after `createAgentGrantRequest`'s own forceRotate+retry), so the worker's
+ * blocked `reconnect_cli` poll bails immediately instead of waiting out its
+ * timeout. `reconnectId` is the `data-cli-reconnect` part id (the reconnect's
+ * toolCallId) so the signal is tied to exactly that reconnect. Best-effort: if
+ * the POST doesn't land, reconnect_cli just falls back to its (short) timeout —
+ * never throw from the failure path.
+ */
+export declare const signalReconnectFailedRequest: (api: ApiClient, input: {
+    readonly provider: string;
+    readonly scopeExternalId: string;
+    readonly reconnectId: string;
+}) => Promise<void>;
+export declare const useCreateAgentGrant: () => import('@tanstack/react-query').UseMutationResult<unknown, Error, {
+    readonly provider: string;
+    readonly scopeExternalId: string;
+}, unknown>;
+export declare const useRevokeAgentGrant: () => import('@tanstack/react-query').UseMutationResult<{
+    status: "revoked";
+}, Error, {
+    readonly grantId: string;
+    readonly provider: string;
+    readonly scopeExternalId: string;
+}, unknown>;

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

@@ -0,0 +1,9 @@
+import { ReactNode } from 'react';
+import { ApiClient } from './client.ts';
+export declare const ApiClientProvider: ({ client, baseUrl, children, }: {
+    readonly client: ApiClient;
+    readonly baseUrl: string;
+    readonly children: ReactNode;
+}) => import("react").JSX.Element;
+export declare const useApiClient: () => ApiClient;
+export declare const useApiBaseUrl: () => string;