@uraiagent/react 0.0.3 → 0.0.5

package/README.md

@@ -15,15 +15,15 @@ npm install @uraiagent/react
 
 ## Usage (React)
 
-Wrap the widget in `<Root>` and pass a single grouped `config` object. `identity`
-and `connection` are required; everything else is optional.
+Render the single `<AgentWidget>` component and pass a grouped `config` object.
+`identity` and `connection` are required; everything else is optional.
 
 ```tsx
-import { Root, AgentWidget } from "@uraiagent/react";
+import { AgentWidget } from "@uraiagent/react";
 
 export default function Agent() {
   return (
-    <Root
+    <AgentWidget
       config={{
         identity: {
           token: "your_widget_token",
@@ -41,6 +41,10 @@ export default function Agent() {
           defaultOpen: false,
           language: "en",
         },
+        design: {
+          colors: { primary: "#6d28d9" },
+          radius: 16,
+        },
         people: {
           agent: { name: "AI Bot" },
           user: { name: "John Doe", email: "john@example.com" },
@@ -54,9 +58,7 @@ export default function Agent() {
           },
         },
       }}
-    >
-      <AgentWidget />
-    </Root>
+    />
   );
 }
 ```
@@ -65,12 +67,13 @@ export default function Agent() {
 
 | Export | Description |
 | --- | --- |
-| `Root` | Context provider + host container. Takes `config` and renders `children`. |
-| `AgentWidget` | The chat UI (trigger button + panel). Render inside `<Root>`. |
+| `AgentWidget` | The widget — one self-contained component. Takes `config`; renders the launcher + chat panel. |
+| `AgentProvider`, `useAgent` | Optional host-app SDK: visitor activity capture + imperative API (`identify`, `track`, `open`…). |
 | `AgentMessage`, `AgentMessageWrapper` | Building blocks for custom message components. |
-| `WidgetConfig` | TypeScript type for the `config` prop. |
+| `WidgetConfig`, `WidgetDesign` | TypeScript types for the `config` prop and its typed design/branding. |
 
-Peer dependencies: `react`, `react-dom`, `framer-motion`, `postcss`.
+Peer dependencies: `react` and `react-dom` (>=18). Everything else, including
+`framer-motion`, is bundled — no extra installs or stylesheet imports.
 
 ---
 

package/dist/AgentWidget.d.ts

@@ -0,0 +1,19 @@
+import { WidgetConfig } from './interfaces/config';
+export type AgentWidgetProps = {
+    /** The full grouped widget configuration. */
+    config: WidgetConfig;
+};
+/**
+ * The widget — one self-contained component.
+ *
+ * Drop it anywhere in your React tree with a `config` and you get the launcher
+ * plus chat panel, fully wired: context providers, realtime, identity, and the
+ * imperative SDK controls. This is the only component you need to render:
+ *
+ * ```tsx
+ * import { AgentWidget } from "@uraiagent/react";
+ *
+ * <AgentWidget config={{ identity: { token: "…" }, connection: {} }} />
+ * ```
+ */
+export declare function AgentWidget({ config }: AgentWidgetProps): import("react/jsx-runtime").JSX.Element;

package/dist/Root.d.ts

@@ -4,5 +4,5 @@ type RootProps = {
     children: React.ReactNode;
     config: WidgetConfig;
 };
-declare function Root({ children, config }: RootProps): import("react/jsx-runtime").JSX.Element;
+declare function Root({ children, config }: RootProps): import("react/jsx-runtime").JSX.Element | null;
 export default Root;

package/dist/Widget.d.ts

@@ -1 +1,6 @@
-export declare function AgentWidget(): import("react/jsx-runtime").JSX.Element;
+/**
+ * The widget's UI shell — launcher trigger + chat panel. Internal: it must render
+ * inside the providers set up by `Root`. Consumers use the unified `AgentWidget`
+ * (which composes `Root` + this) instead of rendering it directly.
+ */
+export declare function WidgetShell(): import("react/jsx-runtime").JSX.Element;

package/dist/contexts/identity/IdentityContext.d.ts

@@ -0,0 +1,33 @@
+import { ReactNode } from 'react';
+import { StoredIdentity } from './identity.storage';
+/** Fields a caller (props, gate, or SDK `identify`) can set on the visitor. */
+export type IdentityPatch = {
+    name?: string;
+    email?: string;
+    phone?: string;
+    userHash?: string;
+    custom?: Record<string, string>;
+};
+export type ResolvedIdentity = {
+    name?: string;
+    email?: string;
+    phone?: string;
+    userHash?: string;
+    custom?: Record<string, string>;
+    verified: boolean;
+};
+type IdentityContextType = {
+    visitorId: string;
+    identity: ResolvedIdentity;
+    /** True once we have an email (from props or the gate). */
+    isKnown: boolean;
+    lastConversationId?: string;
+    /** Merge + persist an identity patch (used by the gate and SDK identify). */
+    setIdentity: (patch: IdentityPatch) => StoredIdentity;
+    setLastConversationId: (id: string | undefined) => void;
+};
+export declare function IdentityProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+export declare function useIdentity(): IdentityContextType;
+export {};

package/dist/contexts/identity/identity.storage.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Persistent visitor identity, stored in localStorage. This replaces the old
+ * single-session cookie as the widget's source of identity. A `visitorId` is
+ * minted once and never rotated client-side; it anchors conversation listing
+ * and activity even before an email is known (anonymous → identified → verified).
+ */
+export interface StoredIdentity {
+    v: 1;
+    /** Stable anonymous visitor handle (nanoid). Minted once. */
+    visitorId: string;
+    /** Identity-verification hash supplied by the host app (HMAC). */
+    userHash?: string;
+    /** Set true once the backend confirms `userHash`. */
+    verified?: boolean;
+    name?: string;
+    email?: string;
+    phone?: string;
+    custom?: Record<string, string>;
+    /** Pointer to the most recent conversation, for resume. */
+    lastConversationId?: string;
+    /** ISO timestamp of the last write. */
+    updatedAt: string;
+}
+/** Subscribe to identity changes. Returns an unsubscribe fn. */
+export declare function subscribeIdentity(listener: (identity: StoredIdentity) => void): () => void;
+/** Read the stored identity, minting + persisting a fresh one on first use. */
+export declare function readIdentity(): StoredIdentity;
+/** Overwrite the stored identity. */
+export declare function writeIdentity(identity: StoredIdentity): void;
+/** Shallow-merge a patch into the stored identity and return the result. */
+export declare function mergeIdentity(patch: Partial<Omit<StoredIdentity, "v" | "visitorId" | "updatedAt">>): StoredIdentity;
+/** One-time migration: adopt a legacy `uraiagent-session` cookie as lastConversationId. */
+export declare function migrateLegacyCookie(): void;

package/dist/contexts/identity/index.d.ts

@@ -0,0 +1,3 @@
+export { IdentityProvider, useIdentity } from './IdentityContext';
+export type { IdentityPatch, ResolvedIdentity } from './IdentityContext';
+export type { StoredIdentity } from './identity.storage';

package/dist/contexts/session/session.api.d.ts

@@ -29,13 +29,52 @@ export interface CreateSessionOptions {
     organizationId: string;
     agentId: string;
     agentName?: string;
+    /** Stable anonymous visitor handle; links the conversation to a durable contact. */
+    visitorId?: string;
+    /** Identity-verification hash (HMAC) computed on the host's server. */
+    userHash?: string;
     user?: {
         name?: string;
         email?: string;
         phone?: string;
+        custom?: Record<string, string>;
     };
 }
+/** A visitor's conversation as summarized for the Home / conversations list. */
+export interface ConversationSummary {
+    sessionId: string;
+    conversationId: string;
+    state: "active" | "resolved" | "archived";
+    lastMessage?: {
+        text: string;
+        from: "agent" | "user" | "event";
+        at: string;
+    };
+    unread?: number;
+    agent?: {
+        name?: string;
+        logo?: string;
+    };
+    updatedAt: string;
+}
+export interface ListConversationsResponse {
+    items: ConversationSummary[];
+    total: number;
+    page: number;
+    limit: number;
+}
 export declare function createSession(api: string, widgetToken: string, options: CreateSessionOptions): Promise<SessionResponse>;
+/**
+ * List the conversations belonging to a visitor (or contact). Best-effort — the
+ * caller treats a failure as "no history yet" so the widget still works before
+ * the backend endpoint exists.
+ */
+export declare function listConversations(api: string, organizationId: string, params: {
+    visitorId?: string;
+    contactId?: string;
+    page?: number;
+    limit?: number;
+}): Promise<ListConversationsResponse>;
 export declare function loadSession(api: string, sessionId: string, widgetToken: string, organizationId: string): Promise<SessionHistoryResponse>;
 export interface SendMessageOptions {
     headers?: Record<string, string>;

package/dist/hooks/index.d.ts

@@ -1,5 +1,6 @@
 export * from './useAsyncFn.ts';
 export * from './useAudioRecord.ts';
+export * from './useAutosizeTextArea';
 export * from './useMountedState';
 export * from './useScrollTo';
 export * from './useToggle';

package/dist/hooks/useAutosizeTextArea.d.ts

@@ -0,0 +1,7 @@
+import { RefObject } from 'react';
+type AutosizeOptions = {
+    minRows?: number;
+    maxRows?: number;
+};
+export declare function useAutosizeTextArea(ref: RefObject<HTMLTextAreaElement | null>, value: string, { minRows, maxRows }?: AutosizeOptions): void;
+export {};

package/dist/hooks/useResolvedConfig.d.ts

@@ -0,0 +1,21 @@
+import { OptionsProps } from '../interfaces/config';
+export type ResolvedConfig = {
+    /** Options with `organizationId`/`design` filled in from the remote config. */
+    options: OptionsProps;
+    /**
+     * Whether the config lookup has settled. Stays `false` while the remote `/chat/config`
+     * lookup is in flight so the widget doesn't flash before it binds. Settling does NOT imply
+     * a usable config — the caller must also check that `options.organizationId` is present.
+     */
+    ready: boolean;
+};
+/**
+ * Resolves the widget's binding (organizationId/design) from its embed token via
+ * `GET /chat/config`, so the host only has to supply a `token`. Values passed explicitly in
+ * props win over the remote copy. Gates rendering until the lookup settles.
+ *
+ * Fails CLOSED: if the lookup errors or the token is unknown, no `organizationId` is resolved and
+ * the widget won't render (unless props supplied one). If there's no token at all, we resolve
+ * immediately from props (back-compat for fully-specified configs).
+ */
+export declare function useResolvedConfig(base: OptionsProps): ResolvedConfig;