@developer.notchatbot/webchat 1.5.2 → 1.6.0

package/dist/types.d.ts

@@ -142,6 +142,15 @@ export interface ChatWindowProps {
     isRated?: boolean;
     onRatingChange?: (isRated: boolean) => void;
     conversationId?: string;
+    /** Configurable auto-survey threshold from the backend; undefined = legacy default (2). */
+    surveyAfterUserMessages?: number;
+    /** Timestamp of the last manual survey request from Livechat; undefined = never requested. */
+    webchatSurveyRequestedAt?: number;
+}
+/** Survey-related conversation state forwarded from the Convex realtime subscription. */
+export interface ConversationSurveyState {
+    surveyAfterUserMessages?: number;
+    webchatSurveyRequestedAt?: number;
 }
 export interface ChatHeaderProps {
     title: string;

package/dist/utils/convex.d.ts

@@ -1,5 +1,5 @@
 import { ConvexReactClient } from 'convex/react';
-import { Message } from '../types';
+import { ConversationSurveyState, Message } from '../types';
 export interface ConvexConnectionData {
     client: ConvexReactClient;
     unsubscribe: (() => void) | null;
@@ -11,9 +11,10 @@ export interface ConvexConnectionData {
  * @param conversationId Conversation ID
  * @param onMessage Callback for new messages
  * @param onChatbotToggle Callback for chatbot activation changes
+ * @param onSurveyStateChange Callback for survey state changes (threshold + manual trigger)
  * @returns Promise that resolves to Convex connection data
  */
-export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void) => Promise<ConvexConnectionData>;
+export declare const initializeConvexConnection: (realtimeEndpoint: string, _chatbotUid: string, conversationId: string, onMessage: (message: Message) => void, onChatbotToggle?: (chatbotActivated: boolean) => void, onSurveyStateChange?: (surveyState: ConversationSurveyState) => void) => Promise<ConvexConnectionData>;
 /**
  * Fetches initial conversation data with messages from Convex
  * @param realtimeEndpoint Realtime service deployment URL

package/dist/utils/self-init.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Self-initialization from the bundle's own <script> URL.
+ *
+ * Used by the Tiendanube 1-click install (Scripts API): Tiendanube injects
+ *   <script src="https://unpkg.com/...bundle.min.umd.cjs?apiKey=<uid>&s=<base64url>">
+ * and the bundle configures itself from those params — zero requests to the
+ * NotChatbot backend on page view. The `s` payload is built SERVER-SIDE when
+ * the script is (re)associated to the store, so this module only decodes it;
+ * it never derives styles on its own.
+ *
+ * ⚠️ CRITICAL BACKWARD COMPATIBILITY ⚠️
+ * Every existing GTM/manual customer loads this same bundle from @latest
+ * WITHOUT query params. For any src without `apiKey` this module MUST return
+ * null and MUST NOT throw — the bundle then behaves exactly as before
+ * (waiting for a manual WebChat.initialize). Keep every code path here
+ * defensive: a broken payload degrades to apiKey-only defaults, never to an
+ * error that could interfere with the bundle load.
+ */
+/** Versioned payload carried in the `s` query param (base64url of its JSON). */
+export interface StylesParamV1 {
+    v: 1;
+    /** Fully-resolved WebChatConfig (minus apiKey), built server-side. */
+    c: Record<string, unknown>;
+    /** CSS for window.injectWebChatCSS (button resize), or null. */
+    css: string | null;
+}
+export interface SelfInitPayload {
+    apiKey: string;
+    /** Resolved config from `s`, or null to initialize with defaults. */
+    config: Record<string, unknown> | null;
+    injectCss: string | null;
+}
+/** Encodes a styles payload to base64url. Exported for tests and tooling; production encoding lives server-side. */
+export declare function encodeStylesParam(payload: StylesParamV1 | Record<string, unknown>): string;
+/**
+ * Parses the bundle's own script src. Returns null unless the URL carries an
+ * `apiKey` query param (the self-init opt-in marker). A present-but-broken
+ * `s` param degrades to apiKey-only (default appearance) instead of failing.
+ */
+export declare function parseSelfInitFromSrc(src: string): SelfInitPayload | null;

package/dist/utils/survey.d.ts

@@ -0,0 +1,30 @@
+import { Message } from '../types';
+/** Legacy hardcoded threshold, used when the backend does not send one. */
+export declare const DEFAULT_SURVEY_AFTER_USER_MESSAGES = 2;
+/**
+ * Resolves the configured auto-survey threshold.
+ * Falls back to the default when the backend does not expose the field yet
+ * or sends something unusable (non-number, NaN, zero/negative).
+ */
+export declare const resolveSurveyThreshold: (value: unknown) => number;
+/** Counts only messages sent by the end user (bot/employee ones don't count). */
+export declare const countUserMessages: (messages: Message[]) => number;
+/**
+ * Whether the survey should auto-open because the user reached the
+ * configured message threshold. Never true for already rated conversations.
+ */
+export declare const shouldAutoShowSurvey: (messages: Message[], surveyAfterUserMessages: number | undefined, isRated: boolean) => boolean;
+/**
+ * Whether a manual survey request (`webchatSurveyRequestedAt`, a timestamp
+ * written by an agent from Livechat) is a new, still unhandled trigger.
+ * Comparing against the last handled value — not just presence — keeps
+ * re-renders and Convex reconnections from re-opening the survey for the
+ * same request, while a fresh timestamp triggers it again.
+ *
+ * Deliberately NOT gated on `isRated`: a manual request fired after a rating
+ * re-opens the survey so the agent can re-validate the experience (the new
+ * rating overwrites the previous one server-side). Stale requests can't leak
+ * across reloads because the backend clears `webchatSurveyRequestedAt` when a
+ * rating is submitted — a present timestamp is always a pending ask.
+ */
+export declare const isNewSurveyRequest: (requestedAt: number | undefined, lastHandledRequestedAt: number | undefined) => boolean;