@uraiagent/react 0.0.3 → 0.0.5

package/dist/interfaces/config.d.ts

@@ -1,68 +1,197 @@
 import { ReactNode } from 'react';
 import { HandoffPayloadType } from '.';
 import { ComponentType } from './components';
+/**
+ * The end user chatting with the widget.
+ *
+ * Provide this only when you have an identified (logged-in) user. If omitted,
+ * the session is treated as anonymous. When supplied, `name` and `email` are
+ * required so the conversation can be attributed and followed up on; `phone`
+ * and everything else is optional.
+ */
 type User = {
-    name?: string;
-    email?: string;
-    phone: string;
+    /** User's display name. Required when a `user` is provided. */
+    name: string;
+    /** User's email address. Required when a `user` is provided. */
+    email: string;
+    /** User's phone number. Optional. */
+    phone?: string;
+    /** URL of the user's avatar image. Optional. */
     avatar?: string;
+    /** Arbitrary string key/value metadata attached to the user. Optional. */
     custom?: Record<string, string>;
+    /**
+     * Identity-verification hash. HMAC-SHA256 of the user's id/email signed with
+     * the widget secret, computed on YOUR server (never in the browser). When
+     * present the backend verifies it and marks the contact as verified so it
+     * can't be impersonated. Optional.
+     */
+    userHash?: string;
 };
+/** The agent/brand identity shown on the widget's side of the conversation. */
 type Agent = {
+    /** Agent display name shown in the header. Optional. */
     name?: string;
+    /** URL of the agent's logo/avatar. Optional. */
     logo?: string;
 };
-type ContainerProps = React.DetailedHTMLProps<React.HTMLAttributes<HTMLDivElement>, HTMLDivElement>;
+/**
+ * Host container configuration.
+ *
+ * Only inline `style` is honored — it is merged onto the widget's host `<div>`
+ * (`.uraiagent-root`). Arbitrary div HTML attributes (id, className, event
+ * handlers, data-*, …) are intentionally NOT applied, so the widget's markup
+ * stays predictable. Retheme via CSS variables (`--uw-*`) instead.
+ */
+type ContainerConfig = {
+    /** Inline styles merged onto the widget's host `<div>`. Optional. */
+    style?: React.CSSProperties;
+};
+/** Default backend API base URL used when `connection.api` is omitted. */
+export declare const DEFAULT_API_BASE_URL = "https://api.uraiagent.com";
+/**
+ * Typed design/branding for the widget.
+ *
+ * Every field is optional. A provided field overrides the stock theme by setting
+ * the matching `--uw-*` CSS variable on the widget root (see `designToStyle`);
+ * anything omitted keeps its default from `style.css`. This is the shape the
+ * dashboard's design editor produces and the backend stores on the widget, so
+ * changing it here is a wire contract — keep it in sync across FE ⇆ widget ⇆ API.
+ */
+export type WidgetDesign = {
+    /** Brand colors (any CSS color string). */
+    colors?: {
+        /** Primary/brand color — header, launcher, user bubble. `--uw-color-primary`. */
+        primary?: string;
+        /** Foreground on top of the primary color. `--uw-color-primary-fg`. */
+        primaryForeground?: string;
+        /** Secondary accent. `--uw-color-accent`. */
+        accent?: string;
+        /** Body text color. `--uw-color-text`. */
+        text?: string;
+        /** Panel surface/background. `--uw-surface`. */
+        surface?: string;
+    };
+    /** Corner radius of the panel/controls, in px. `--uw-radius`. */
+    radius?: number;
+    /** Corner radius of message bubbles, in px. `--uw-radius-bubble`. */
+    bubbleRadius?: number;
+    /** Typography. */
+    font?: {
+        /** CSS font-family stack. `--uw-font`. */
+        family?: string;
+        /** Base font size, in px. `--uw-font-size`. */
+        size?: number;
+    };
+};
+/**
+ * Map a typed {@link WidgetDesign} to the inline `--uw-*` CSS custom properties
+ * applied on the widget root. Inline vars beat the zero-specificity
+ * `:where(.uraiagent-root)` defaults, so only the fields you set take effect and
+ * everything else keeps its stock token. Returns an empty object for empty input.
+ */
+export declare function designToStyle(design?: WidgetDesign): React.CSSProperties;
 /**
  * Public, grouped widget configuration.
  *
- * Styling is NOT configured here — the widget is pure namespaced CSS
- * (`.uraiagent-*`) + design tokens (`--uw-*`). Retheme from your own stylesheet
- * (e.g. `.uraiagent-root { --uw-color-primary: #6d28d9 }`). So there is no
- * `theme.tokens` / `theme.classNames` — only the host `container` survives.
+ * Branding lives in `design` (typed `--uw-*` overrides, applied on the root). You
+ * can still retheme purely from your own stylesheet (`.uraiagent-root {
+ * --uw-color-primary: #6d28d9 }`) — `design` is just the ergonomic, typed path and
+ * wins over the stock defaults. Only the host `container` survives beyond that.
  */
 export type WidgetConfig = {
+    /** Identifiers that bind the widget to a dashboard-configured agent. Required. */
     identity: {
-        /** Widget ID from the dashboard. */
+        /** Widget embed token from the dashboard. Required. */
         token: string;
-        organizationId: string;
-        agentId: string;
+        /**
+         * Organization ID that owns the widget. Optional — resolved from the token via
+         * `GET /chat/config` on load. Provide it only to skip/override the remote lookup.
+         */
+        organizationId?: string;
+        /**
+         * Agent ID that conversations are routed to. Optional — resolved from the token via
+         * `GET /chat/config` on load. Provide it only to skip/override the remote lookup.
+         */
+        agentId?: string;
     };
+    /** Backend connection settings. Required (but every field has a sensible default). */
     connection: {
-        /** Backend API base URL, e.g. "https://api.example.com". */
-        api: string;
+        /**
+         * Backend API base URL, e.g. "https://api.example.com".
+         * Optional — defaults to `https://api.uraiagent.com` when omitted.
+         */
+        api?: string;
+        /** Extra HTTP headers sent with every widget API request. Optional. */
         headers?: Record<string, string>;
+        /** Extra query-string params appended to widget API requests. Optional. */
         queryParams?: Record<string, string>;
     };
+    /** Copy and content shown inside the widget. Optional. */
     content?: {
+        /** Message shown when the conversation first opens. Optional. */
         initialMessage?: string;
+        /** Placeholder text for the message input. Optional. */
         inputPlaceholder?: string;
+        /** Sub-header description block. Optional. */
         description?: {
+            /** Whether the description is visible. Optional. */
             visible?: boolean;
+            /** The description text. Optional. */
             text?: string;
         };
-        /** Custom node rendered inside the trigger button. */
+        /** Custom node rendered inside the trigger button. Optional. */
         triggerIcon?: ReactNode;
     };
+    /** Runtime behavior toggles. Optional. */
     behavior?: {
+        /** Open the widget automatically on load. Optional (default: false). */
         defaultOpen?: boolean;
+        /** Close the widget when the user clicks outside it. Optional (default: true). */
         closeOutside?: boolean;
+        /** Enable verbose debug logging. Optional (default: false). */
         debug?: boolean;
+        /** Enable non-fatal configuration warnings. Optional. */
         warn?: boolean;
+        /** UI language code, e.g. "en", "fr". Optional (falls back to browser/default locale). */
         language?: string;
+        /**
+         * Preview/offline mode. When true the widget renders from the given config
+         * WITHOUT binding to the backend: no `GET /chat/config` lookup, no session
+         * creation, no realtime socket. Use it to render a live, inert preview (e.g.
+         * the dashboard design editor). Optional (default: false). Not for production.
+         */
+        preview?: boolean;
     };
+    /**
+     * Typed design/branding overrides. Optional. Wins over the stock theme and over
+     * the remote design resolved from `GET /chat/config`.
+     */
+    design?: WidgetDesign;
+    /** Participants in the conversation. Optional. */
     people?: {
+        /**
+         * The identified end user. Optional — omit for an anonymous session.
+         * When provided, `name` and `email` are required.
+         */
         user?: User;
+        /** The agent/brand identity. Optional. */
         agent?: Agent;
     };
+    /** Lifecycle event callbacks. Optional. */
     on?: {
+        /** Called when the widget is closed. Optional. */
         close?: () => void;
+        /** Called when the conversation is handed off to a human. Optional. */
         handoff?: (handout: HandoffPayloadType) => void;
     };
-    /** Custom message/event components. */
+    /** Custom message/event components. Optional. */
     components?: ComponentType[];
-    /** Props spread onto the widget's host container <div>. */
-    container?: ContainerProps;
+    /**
+     * Host container configuration. Optional.
+     * Only `style` is applied to the widget's host `<div>`.
+     */
+    container?: ContainerConfig;
 };
 /**
  * Flat, resolved config — the shape every internal component reads via
@@ -72,6 +201,10 @@ export type OptionsProps = {
     token: string;
     organizationId: string;
     agentId: string;
+    /** Typed design/branding — from props or resolved from `GET /chat/config`. */
+    design?: WidgetDesign;
+    /** Preview/offline mode: render from config without binding to the backend. */
+    preview?: boolean;
     api: string;
     headers?: Record<string, string>;
     queryParams?: Record<string, string>;
@@ -92,7 +225,7 @@ export type OptionsProps = {
     components?: ComponentType[];
     onClose?: () => void;
     onHandoff?: (handout: HandoffPayloadType) => void;
-    container?: ContainerProps;
+    container?: ContainerConfig;
 };
 /** Flatten the grouped public config into the internal flat shape. */
 export declare function normalizeConfig(c: WidgetConfig): OptionsProps;

package/dist/sdk/AgentContext.d.ts

@@ -0,0 +1,32 @@
+import { ReactNode } from 'react';
+import { AgentEventName, IdentifyInput } from './agent-store';
+export interface AgentApi {
+    /** Stable anonymous visitor id (localStorage). */
+    visitorId: string;
+    /** Merge identity + link the visitor to a contact (optionally verified). */
+    identify: (user: IdentifyInput) => Promise<void>;
+    /** Record a custom activity event. */
+    track: (name: string, data?: Record<string, unknown>) => void;
+    /** Open the widget. */
+    open: () => void;
+    /** Close the widget. */
+    close: () => void;
+    /** Send a message (creating a conversation if needed). */
+    sendMessage: (text: string) => Promise<void>;
+    /** Subscribe to widget lifecycle events. Returns an unsubscribe fn. */
+    on: (event: AgentEventName, cb: (payload?: unknown) => void) => () => void;
+}
+/**
+ * Wrap your app in this to (a) capture visitor activity and (b) use
+ * `useAgent()` anywhere. It does NOT own widget config — render the widget
+ * (`<AgentWidget config={…} />`) as usual; config stays on the widget. This
+ * provider only adds the activity + imperative SDK layer, bridged through the
+ * shared store.
+ */
+export declare function AgentProvider({ children }: {
+    children: ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Access the widget SDK. Must be used inside `<AgentProvider>`.
+ */
+export declare function useAgent(): AgentApi;

package/dist/sdk/AgentControls.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Invisible bridge rendered inside Root. Feeds the singleton store the config
+ * Root already resolved (so config stays on Root) and registers the imperative
+ * controls the SDK exposes via `useAgent`.
+ */
+export declare function AgentControls(): null;

package/dist/sdk/activity-capture.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Start framework-agnostic activity capture: sessionStarted, initial + SPA
+ * pageViews (via a history.pushState monkey-patch), and unload flushing.
+ * Returns a cleanup fn that restores history and removes listeners.
+ */
+export declare function startActivityCapture(): () => void;

package/dist/sdk/agent-store.d.ts

@@ -0,0 +1,59 @@
+import { StoredIdentity } from '../contexts/identity/identity.storage';
+export interface ActivityEvent {
+    name: string;
+    date: string;
+    data?: Record<string, unknown>;
+}
+export type IdentifyInput = {
+    email?: string;
+    name?: string;
+    phone?: string;
+    userHash?: string;
+    custom?: Record<string, string>;
+};
+/** Imperative hooks the widget (inside Root) registers so the SDK can drive it. */
+export interface AgentControls {
+    open: () => void;
+    close: () => void;
+    sendMessage: (text: string) => Promise<void>;
+}
+export type AgentEventName = "open" | "close" | "message" | "handoff";
+type Listener = (payload?: unknown) => void;
+/**
+ * Process-wide singleton bridging the host app (via `useAgent`) and the
+ * widget (mounted inside `Root`). Root feeds it the connection config + controls;
+ * the SDK provider feeds it activity. Config stays on Root — the store just
+ * receives what Root already resolved.
+ */
+declare class AgentStore {
+    private api?;
+    private organizationId?;
+    private visitorId?;
+    private token?;
+    private controls;
+    private buffer;
+    private timer;
+    private startedAt;
+    private readonly listeners;
+    /** Called by Root once config + identity resolve. Idempotent. */
+    configure(cfg: {
+        api: string;
+        organizationId: string;
+        visitorId: string;
+        token?: string;
+    }): void;
+    getVisitorId(): string;
+    attachControls(controls: AgentControls): void;
+    detachControls(controls: AgentControls): void;
+    track(name: string, data?: Record<string, unknown>): void;
+    /** Send buffered events. `useBeacon` for unload (best-effort, keepalive). */
+    flush(useBeacon?: boolean): Promise<void>;
+    open(): void;
+    close(): void;
+    sendMessage(text: string): Promise<void>;
+    identify(input: IdentifyInput): Promise<StoredIdentity>;
+    on(event: AgentEventName, cb: Listener): () => void;
+    emit(event: AgentEventName, payload?: unknown): void;
+}
+export declare const agentStore: AgentStore;
+export {};

package/dist/sdk/index.d.ts

@@ -0,0 +1,5 @@
+export { AgentProvider, useAgent } from './AgentContext';
+export type { AgentApi } from './AgentContext';
+export { AgentControls } from './AgentControls';
+export { agentStore } from './agent-store';
+export type { ActivityEvent, AgentEventName, IdentifyInput, } from './agent-store';

package/dist/utils/index.d.ts

@@ -26,7 +26,8 @@ declare const get: <K extends keyof typeof json>(key: K) => {
         "update-dashboard-agent": string;
     };
     peerDependencies: {
-        "framer-motion": string;
+        react: string;
+        "react-dom": string;
     };
     devDependencies: {
         "@eslint/js": string;
@@ -55,13 +56,14 @@ declare const get: <K extends keyof typeof json>(key: K) => {
         url: string;
     };
     main: string;
+    module: string;
     types: string;
     exports: {
         ".": {
-            require: string;
+            types: string;
             import: string;
+            require: string;
             default: string;
-            types: string;
         };
     };
     dependencies: {
@@ -76,7 +78,6 @@ declare const get: <K extends keyof typeof json>(key: K) => {
         nanoid: string;
         "pusher-js": string;
         "react-markdown": string;
-        "react-textarea-autosize": string;
         "remark-gfm": string;
         zod: string;
     };