@convai/web-widget 0.2.1 → 0.3.1

package/ui/react/components/ConvaiWidget.d.ts

@@ -1,14 +1,15 @@
+import { type LiveClientFields } from "../hooks/useLiveClient";
 import type { LinkPreviewResolver } from "@convai/web-sdk/core";
 import type { IConvaiClient, PublishedChatConnectOptions } from "@convai/web-sdk/core";
 import type { PublishedChatDescriptor } from "@convai/web-sdk/embed";
 interface ConvaiWidgetProps {
-    /** Convai client instance (required) */
-    convaiClient: IConvaiClient & {
-        activity?: string;
-        isAudioMuted: boolean;
-        isVideoEnabled: boolean;
-        isScreenShareActive: boolean;
-    };
+    /**
+     * The Convai client (required). Either `useConvaiClient`'s result, or any
+     * `ConvaiClient` — one built with `new ConvaiClient(...)`, or the character's
+     * own client from `@convai/embody`. The widget subscribes to a bare client's
+     * events itself and never opens a second connection.
+     */
+    convaiClient: IConvaiClient & Partial<LiveClientFields>;
     /**
      * Show video toggle button in settings (default: true).
      * Only works if connection type is "video". If false, hides the video button.

package/ui/react/hooks/useCharacterInfo.d.ts

@@ -6,7 +6,7 @@ import { type CharacterInfo } from "@convai/web-sdk/core";
  * the same code rather than a hand-synced copy of it.
  *
  * @param characterId - Character to look up
- * @param apiKey - Convai API key, sent as `X-API-Key`
+ * @param apiKey - Convai API key, sent as `CONVAI-API-KEY`
  * @param authToken - Preferred over `apiKey`, sent as `API-AUTH-TOKEN`
  * @param baseUrl - Origin to ask; defaults to `https://api.convai.com`. Pass
  *   `client.characterInfoUrl` so a non-SaaS deployment is not asked to send

package/ui/react/hooks/useLiveClient.d.ts

@@ -0,0 +1,26 @@
+import type { IConvaiClient } from "@convai/web-sdk/core";
+/** The fields `useConvaiClient` adds on top of the client. */
+export interface LiveClientFields {
+    activity: string;
+    isAudioMuted: boolean;
+    isVideoEnabled: boolean;
+    isScreenShareActive: boolean;
+}
+/** True for a `useConvaiClient` result, which carries the UI fields itself. */
+export declare function isManagedClient(client: object): boolean;
+/**
+ * The four UI fields for `client`: its own when `useConvaiClient` supplied
+ * them, otherwise read live from the client, re-rendering on every change.
+ */
+export declare function useLiveClient(client: IConvaiClient & Partial<LiveClientFields>): LiveClientFields;
+/**
+ * The client as the widget should see it: a `useConvaiClient` result as-is,
+ * otherwise a view that adds the four UI fields and changes identity on every
+ * client event — exactly how a `useConvaiClient` result behaves, so the widget
+ * and its children re-render and re-run their effects the same way.
+ *
+ * A Proxy, not a copy: reads, writes and `this` inside methods all reach the
+ * real client, and only the four fields are answered here. The app's own
+ * reference to the client is never modified.
+ */
+export declare function useLiveClientView<C extends IConvaiClient & Partial<LiveClientFields>>(client: C): C & LiveClientFields;