@askly/widget 2.8.0 → 2.10.0

package/README.md

@@ -163,8 +163,21 @@ Askly.init({ appId: "YOUR_APP_ID", greeting: { message: "Need a hand?", delayMs:
 <script src="…/widget.js" data-app-id="YOUR_APP_ID" data-greeting="false" async></script>
 ```
 
-The widget dispatches `askly:greeting:shown`, `askly:greeting:clicked` and
-`askly:greeting:dismissed` on `window` for analytics.
+For analytics, listen for `greeting:shown`, `greeting:clicked` and `greeting:dismissed` with
+`Askly.on()` (see the JavaScript API below).
+
+### 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
 
@@ -214,7 +227,63 @@ Notes:
 - **Optimized:** on non-matching pages the path check runs *before* anything mounts, so there's no DOM node, no React root, and no config network request — the SDK does essentially nothing.
 - The decision is evaluated once at init; it's a UX targeting tool, not a security boundary (the script can still be loaded on any page).
 
-## Lifecycle Callbacks
+## JavaScript API
+
+Everything below is on the global `Askly` (script tag) or the default export (npm). Calls made
+straight after `Askly.init()` are held and carried out once the widget has mounted.
+
+### Controlling the widget
+
+| Method | What it does |
+| :--- | :--- |
+| `Askly.open()` / `Askly.show()` | Open the chat panel. |
+| `Askly.close()` / `Askly.hide()` | Close it. |
+| `Askly.toggle()` | Open if closed, close if open. |
+| `Askly.showSpace(space)` | Open on `"home"`, `"messages"` or `"help"`. |
+| `Askly.showNewMessage(text?)` | Open the chat with the message box focused, optionally pre-filled. Nothing is sent. |
+| `Askly.sendMessage(text)` | Open the chat and send `text` as the visitor. It passes the same checks as a typed message; if one is pending (email required, security check) it waits in the message box. |
+| `Askly.showArticle(id)` | Open a help article by id. |
+| `Askly.update(config)` | Change display settings without re-initialising, e.g. `{ themeColor, theme, organizationName, welcomeMessage, buttonShape }`. |
+| `Askly.isOpen()` | `true` while the panel is open. |
+| `Askly.getUnreadCount()` | Agent replies the visitor has not seen (the launcher badge). |
+| `Askly.getVisitorId()` | This browser's anonymous visitor id (`""` before mount). |
+| `Askly.ready()` | A promise that resolves once the widget has mounted and applied its configuration. |
+
+```javascript
+document.querySelector("#contact-sales").addEventListener("click", () => {
+  Askly.showNewMessage("Hi, I'd like to talk about the Business plan.");
+});
+```
+
+### Events
+
+`Askly.on(name, handler)` returns a function that removes the listener; `Askly.off(name, handler)`
+and `Askly.once(name, handler)` are also available. A handler that throws is logged and does not
+affect the widget.
+
+| Event | Payload | When |
+| :--- | :--- | :--- |
+| `ready` | `{ visitorId }` | The widget has mounted and applied its configuration. |
+| `open` / `close` | none | The panel was opened or closed. |
+| `message:sent` | `{ text, conversationId }` | The visitor sent a message. |
+| `message:received` | `{ text, conversationId, from, messageId }` | A reply arrived; `from` is `"ai"` or `"agent"`. |
+| `unread` | `{ count }` | The number of unseen agent replies changed. |
+| `escalated` | `{ conversationId }` | The conversation was handed to a human. |
+| `lead:captured` | none | The visitor left an email address. |
+| `identify:success` / `identify:error` | `{ userId, status? }` | The server accepted or refused `identify()`. |
+| `greeting:shown` / `greeting:clicked` / `greeting:dismissed` | none | Greeting bubble activity. |
+| `error` | `{ message, status? }` | A message could not be sent. |
+
+```javascript
+Askly.on("message:received", ({ from }) => analytics.track("support_reply", { from }));
+Askly.on("unread", ({ count }) => { document.title = count ? `(${count}) Acme` : "Acme"; });
+```
+
+TypeScript users can import the payload types: `import type { AsklyEventMap } from "@askly/widget"`.
+
+### Callbacks at init (older style)
+
+These still work and are called alongside the events above.
 
 Callbacks are functions, so they can only be attached in code (not from the portal):
 

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;
+}

package/dist/index.d.ts

@@ -1,3 +1,4 @@
+import { type AsklyEventMap, type AsklyEventName, type AsklyEventHandler, type AsklySpace } from "./core/events";
 import { type AsklyIdentity } from "./identity";
 export interface AsklyConfig {
     appId?: string;
@@ -75,5 +76,42 @@ declare const Askly: {
     close: () => void;
     /** Toggle the chat panel. */
     toggle: () => void;
+    /** Aliases of open() / close(). */
+    show: () => void;
+    hide: () => void;
+    /** Whether the chat panel is open right now. */
+    isOpen: () => boolean;
+    /** Agent replies the visitor has not seen yet (the number on the launcher badge). */
+    getUnreadCount: () => number;
+    /** This browser's anonymous visitor id, or "" before the widget has mounted. */
+    getVisitorId: () => string;
+    /**
+     * Listen for a widget event. Returns a function that removes the listener.
+     *
+     *   Askly.on("message:received", ({ text, from }) => analytics.track("support_reply", { from }));
+     *   Askly.on("unread", ({ count }) => setBadge(count));
+     */
+    on: <K extends keyof AsklyEventMap>(name: K, handler: AsklyEventHandler<K>) => (() => void);
+    off: <K_1 extends keyof AsklyEventMap>(name: K_1, handler: AsklyEventHandler<K_1>) => void;
+    once: <K_2 extends keyof AsklyEventMap>(name: K_2, handler: AsklyEventHandler<K_2>) => (() => void);
+    /** Resolves when the widget has mounted and applied its configuration. */
+    ready: () => Promise<void>;
+    /** Open the widget on a section: "home", "messages" or "help". */
+    showSpace: (space: AsklySpace) => void;
+    /** Open the chat with the composer ready, optionally pre-filled. Nothing is sent. */
+    showNewMessage: (text?: string) => void;
+    /**
+     * Open the chat and send a message as the visitor. It goes through the same checks as a
+     * typed message; if one is pending (email required, security check) it waits in the composer.
+     */
+    sendMessage: (text: string) => void;
+    /** Open a help article by id, as listed in the Help tab. */
+    showArticle: (articleId: string) => void;
+    /**
+     * Change display settings on the mounted widget without re-initialising: the fields the
+     * portal controls, e.g. `{ themeColor, theme, organizationName, welcomeMessage, buttonShape }`.
+     */
+    update: (config: Record<string, any>) => void;
 };
 export default Askly;
+export type { AsklyIdentity, AsklyEventMap, AsklyEventName, AsklyEventHandler, AsklySpace };