@askly/widget 2.7.0 → 2.9.0

package/README.md

@@ -108,10 +108,11 @@ const hash = crypto
 
 Without a valid `hash` the traits are still used locally, but Askly will not link the accounts.
 
-> **Known limitation:** a signature is accepted for 5 minutes from its `timestamp`. On a page that
-> stays open longer, call `Askly.identify()` again with a freshly generated `hash` and `timestamp`
-> (for example on a timer, or before the user opens the chat). If `identify()` is rejected, the
-> reason is logged to the browser console.
+The `hash` only has to be fresh at the moment `identify()` (or `init()`) runs: it is valid for 5
+minutes from its `timestamp`. Once Askly has verified it, the widget holds a session for that user
+and keeps renewing it, so a page that stays open for hours keeps working without a new hash. If
+`identify()` is rejected, the reason is logged to the browser console and messages are sent as
+the anonymous visitor.
 
 #### Logging out
 
@@ -165,6 +166,19 @@ Askly.init({ appId: "YOUR_APP_ID", greeting: { message: "Need a hand?", delayMs:
 The widget dispatches `askly:greeting:shown`, `askly:greeting:clicked` and
 `askly:greeting:dismissed` on `window` for analytics.
 
+### Live replies
+
+When one of your agents replies, the widget receives it over a live connection the moment it is
+sent, rather than checking for it every few seconds. This works with the chat panel closed too:
+the launcher shows a badge with the number of new replies, and opening it goes straight to that
+conversation.
+
+There is nothing to configure. The connection is opened once a visitor has started a conversation
+and only while the tab is visible. If it cannot be established (a network that blocks streaming,
+or a self-hosted server older than this feature) the widget falls back to checking every few
+seconds while the chat is open, as before. If your site sets a Content Security Policy, the Askly
+API origin must be in `connect-src`.
+
 ### Asking visitors for their email
 
 Anonymous visitors can't be replied to once they close the tab — the answer just waits in a widget

package/dist/core/events.d.ts

@@ -0,0 +1,96 @@
+/**
+ * The widget's public event bus and its command channel.
+ *
+ * Events flow out: the mounted widget emits them and host code listens with `Askly.on()`.
+ * Commands flow in: `Askly.open()`, `Askly.sendMessage()` and friends post a command that the
+ * mounted widget carries out. Commands posted before the widget has mounted are held and
+ * delivered when it does, so a host can call them straight after `Askly.init()`.
+ */
+export interface AsklyEventMap {
+    /** The widget has mounted and loaded its configuration. */
+    ready: {
+        visitorId: string;
+    };
+    open: undefined;
+    close: undefined;
+    /** The visitor sent a message. */
+    "message:sent": {
+        text: string;
+        conversationId: string;
+    };
+    /** A reply arrived, from the AI or from one of your agents. */
+    "message:received": {
+        text: string;
+        conversationId: string;
+        from: "ai" | "agent";
+        messageId?: string;
+    };
+    /** The number of unread agent replies changed. */
+    unread: {
+        count: number;
+    };
+    /** The conversation was handed to a human. */
+    escalated: {
+        conversationId: string;
+    };
+    /** The visitor left an email address in the capture form. */
+    "lead:captured": undefined;
+    "identify:success": {
+        userId: string;
+    };
+    "identify:error": {
+        userId: string;
+        status?: number;
+    };
+    "greeting:shown": undefined;
+    "greeting:clicked": undefined;
+    "greeting:dismissed": undefined;
+    /** A request failed in a way the visitor was told about. */
+    error: {
+        message: string;
+        status?: number;
+    };
+}
+export type AsklyEventName = keyof AsklyEventMap;
+export type AsklyEventHandler<K extends AsklyEventName> = (payload: AsklyEventMap[K]) => void;
+export declare function on<K extends AsklyEventName>(name: K, handler: AsklyEventHandler<K>): () => void;
+export declare function off<K extends AsklyEventName>(name: K, handler: AsklyEventHandler<K>): void;
+export declare function once<K extends AsklyEventName>(name: K, handler: AsklyEventHandler<K>): () => void;
+export declare function emit<K extends AsklyEventName>(name: K, ...payload: AsklyEventMap[K] extends undefined ? [] : [AsklyEventMap[K]]): void;
+export type AsklySpace = "home" | "messages" | "help";
+export type AsklyCommand = {
+    type: "open";
+} | {
+    type: "close";
+} | {
+    type: "toggle";
+} | {
+    type: "showSpace";
+    space: AsklySpace;
+} | {
+    type: "showNewMessage";
+    text?: string;
+} | {
+    type: "sendMessage";
+    text: string;
+} | {
+    type: "showArticle";
+    articleId: string;
+} | {
+    type: "update";
+    config: Record<string, any>;
+};
+export declare function expectMount(): void;
+export declare function sendCommand(command: AsklyCommand): void;
+/** Called by the mounted widget. Returns the unsubscribe; held commands are delivered now. */
+export declare function handleCommands(handler: (command: AsklyCommand) => void): () => void;
+/** Drop commands held for a widget that will not mount (shutdown before mount). */
+export declare function clearPendingCommands(): void;
+/** What the getters on `Askly` report. Written by the mounted widget. */
+export declare const widgetState: {
+    ready: boolean;
+    open: boolean;
+    unread: number;
+    visitorId: string;
+};
+export declare function resetWidgetState(): void;

package/dist/core/format.d.ts

@@ -0,0 +1,2 @@
+/** Small display helpers shared by the UI components. */
+export declare function formatTime(dateAny: any): string;

package/dist/core/greeting.d.ts

@@ -0,0 +1,10 @@
+export declare const GREETING_DEFAULT_DELAY_MS = 3000;
+export declare const GREETING_MAX_CHIPS = 3;
+/**
+ * The greeting line. `{ai_name}` and `{organizationName}` are filled in from config; with no
+ * AI persona (or no AI answering at all) the default never promises one.
+ */
+export declare function buildGreeting(template: unknown, aiName: string | null, organizationName: string): string;
+export declare function greetingDismissed(scope: string): boolean;
+export declare function rememberGreetingDismissed(scope: string): void;
+export declare function emitGreetingEvent(type: "shown" | "dismissed" | "clicked"): void;

package/dist/core/session.d.ts

@@ -0,0 +1,59 @@
+/**
+ * The widget's session with the server.
+ *
+ * A short-lived token the server issues for this browser (see /widget/session). Once the
+ * widget has one, requests carry it in the Authorization header instead of putting the
+ * visitor id in URLs or replaying the host's signature, and it remembers what was already
+ * proven: a verified user (so a five-minute signature only has to be fresh once) and a
+ * passed security check (so guests are challenged once, not per message). Held in memory
+ * only. Servers older than this feature answer 404 and the widget carries on without one.
+ */
+export interface WidgetSessionOptions {
+    /** Full URL of a widget endpoint, e.g. api("/session"). */
+    api: (path: string) => string;
+    getOrganizationId: () => string | undefined;
+    getVisitorId: () => string;
+    /** Called when what the session vouches for changes (so the UI can re-render). */
+    onChange: () => void;
+}
+export type SessionUrl = string | ((hasSession: boolean) => string);
+export declare class WidgetSession {
+    private options;
+    /** The current token, or null. */
+    token: string | null;
+    /** False once the server has answered 404 for sessions: an older server. Final. */
+    supported: boolean;
+    /** The host user id the session vouches for, if any. Compared with the current identity
+     *  so a session verified for one user is never used to speak for another. */
+    userId: string | null;
+    /** The session has passed the security check. */
+    human: boolean;
+    private pending;
+    /** Why the last attempt to start or renew failed: the server refused the token
+     *  ("rejected"), or something temporary got in the way ("transient"). */
+    private lastFailure;
+    constructor(options: WidgetSessionOptions);
+    /** Take the session fields from a server response, if it carries any. */
+    apply(data: any): void;
+    clear(): void;
+    /**
+     * Start a session from the visitor id, or renew one from its (possibly expired) token.
+     * Concurrent callers share one request. Resolves to the token, or null.
+     */
+    start(renewFrom?: string): Promise<string | null>;
+    /**
+     * fetch() with the session token attached. `url` may depend on whether there is a token
+     * (the poll leaves the visitor id out of its URL when there is one). Resolves to the
+     * response and the token the (final) request went out with.
+     *
+     * On 401 the token is renewed once and the request retried. Only when the server refuses
+     * the token outright is the session dropped for an anonymous one; a renewal that failed
+     * for a passing reason (rate limit, deploy, network) leaves a verified session intact and
+     * the 401 is returned for the caller to treat as a failed request.
+     */
+    request(url: SessionUrl, init?: RequestInit): Promise<{
+        res: Response;
+        token: string | null;
+    }>;
+    fetch(url: SessionUrl, init?: RequestInit): Promise<Response>;
+}

package/dist/core/storage.d.ts

@@ -0,0 +1,4 @@
+/** Local persistence for chat history. A cache, never the record: the server has the truth. */
+import type { SavedConversation } from "./types";
+export declare function loadConversations(key: string): SavedConversation[];
+export declare function saveConversations(key: string, conversations: SavedConversation[]): void;

package/dist/core/types.d.ts

@@ -0,0 +1,65 @@
+/** Shapes shared by the widget's core and its UI components. */
+import type { MessageFormat } from "../markdown";
+export interface ChatWidgetProps {
+    orgId?: string;
+    organizationName?: string;
+    themeColor?: string;
+    theme?: "light" | "dark" | "auto";
+    position?: "left" | "right";
+    orgServerRoute: string;
+    enableVoiceChat?: boolean;
+    readAloud?: boolean;
+    welcomeMessage?: string;
+    placeholderText?: string;
+    organizationLogo?: string;
+    buttonIcon?: string;
+    buttonShape?: "round" | "square";
+    autoOpen?: boolean;
+    greeting?: boolean | {
+        message?: string;
+        delayMs?: number;
+    };
+    showTimestamp?: boolean;
+    soundEnabled?: boolean;
+    soundVolume?: number;
+    poweredBy?: string;
+    userId?: string;
+    timestamp?: number;
+    signature?: string;
+    turnstileSiteKey?: string;
+    excludePaths?: string[];
+    includePaths?: string[];
+    configOverride?: Record<string, any>;
+    resetGeneration?: number;
+    onMessageSent?: (message: string) => void;
+    onMessageReceived?: (reply: string) => void;
+    onChatOpened?: () => void;
+    onChatClosed?: () => void;
+    onEscalation?: (data: any) => void;
+}
+export interface Message {
+    role: "user" | "agent";
+    content: string;
+    timestamp?: Date;
+    format?: MessageFormat;
+    kind?: "greeting";
+    messageId?: string;
+}
+export interface SavedConversation {
+    id: string;
+    messages: Message[];
+    lastUpdated: string;
+    unread?: number;
+}
+export interface Article {
+    id: string;
+    title: string;
+    content: string;
+    document_type: string;
+    score?: number;
+}
+export type WidgetTab = "explore" | "messages" | "help";
+export interface Faq {
+    question: string;
+    answer: string;
+}