@customerhero/js 1.0.0 → 1.1.0

package/dist/index.d.cts

@@ -123,6 +123,133 @@ interface IdentityData {
     userHash?: string;
     customProperties?: Record<string, string | number | boolean>;
 }
+type TriggerConditionNode = {
+    all: TriggerConditionNode[];
+} | {
+    any: TriggerConditionNode[];
+} | TriggerConditionLeaf;
+type TriggerConditionLeaf = {
+    kind: "url_path";
+    op: "equals" | "contains" | "regex" | "starts_with";
+    value: string;
+} | {
+    kind: "url_query";
+    key: string;
+    op: "equals" | "contains" | "exists";
+    value?: string;
+} | {
+    kind: "referrer";
+    op: "contains" | "equals" | "regex";
+    value: string;
+} | {
+    kind: "time_on_page";
+    seconds: number;
+} | {
+    kind: "scroll_depth";
+    percent: number;
+} | {
+    kind: "exit_intent";
+} | {
+    kind: "device";
+    op: "equals";
+    value: "mobile" | "tablet" | "desktop";
+} | {
+    kind: "browser_language";
+    op: "in";
+    values: string[];
+} | {
+    kind: "visitor_trait";
+    key: string;
+    op: "equals" | "exists" | "gt" | "lt";
+    value?: string | number | boolean;
+} | {
+    kind: "return_visit";
+    op: "gte" | "eq";
+    count: number;
+};
+type TriggerAction = {
+    kind: "open_widget";
+} | {
+    kind: "send_message";
+    message: string;
+} | {
+    kind: "show_form";
+} | {
+    kind: "open_with_prefill";
+    prefill: string;
+};
+type TriggerFrequency = "once_ever" | "once_per_session" | "every_time";
+interface TriggerDefinition {
+    id: string;
+    priority: number;
+    conditions: TriggerConditionNode;
+    action: TriggerAction;
+    frequency: TriggerFrequency;
+}
+type PreChatFieldKind = "name" | "email" | "phone" | "text" | "textarea" | "select" | "consent";
+type PreChatField = {
+    kind: "name";
+    required?: boolean;
+    label?: string;
+} | {
+    kind: "email";
+    required?: boolean;
+    label?: string;
+    validateMx?: boolean;
+} | {
+    kind: "phone";
+    required?: boolean;
+    label?: string;
+} | {
+    kind: "text";
+    key: string;
+    label: string;
+    required?: boolean;
+    maxLength?: number;
+} | {
+    kind: "textarea";
+    key: string;
+    label: string;
+    required?: boolean;
+    maxLength?: number;
+} | {
+    kind: "select";
+    key: string;
+    label: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    required?: boolean;
+} | {
+    kind: "consent";
+    key: string;
+    label: string;
+    url?: string;
+    required: true;
+};
+interface PreChatFormConfig {
+    fields: PreChatField[];
+    title?: string | null;
+    description?: string | null;
+    submitLabel: string;
+    /** When true, an identified visitor (CustomerHero.identify already called)
+     *  bypasses the form. */
+    skipForIdentified: boolean;
+}
+interface PreChatSubmission {
+    name?: string;
+    email?: string;
+    phone?: string;
+    /** Keyed answers from text/textarea/select/consent fields. */
+    properties?: Record<string, string | number | boolean>;
+}
+interface ConsentSettings {
+    /** When true, all condition kinds are evaluated. When false (default), only
+     *  direct launcher clicks fire — URL/time/scroll/exit-intent/trait
+     *  conditions stay dormant. */
+    analytics: boolean;
+}
 interface ChatState {
     messages: ChatMessage[];
     isOpen: boolean;
@@ -137,6 +264,26 @@ interface ChatState {
     locale: SupportedLocale;
     /** True when the active locale is right-to-left. */
     isRtl: boolean;
+    /** Triggers loaded from the server config (active + in-window). */
+    triggers: TriggerDefinition[];
+    /** Pre-chat form configuration, if any. */
+    preChatForm: PreChatFormConfig | null;
+    /**
+     * True when the pre-chat form must be shown before the next chat turn.
+     * Flipped by trigger actions, by the first sendMessage when a form is
+     * configured and not yet submitted, and cleared on submit.
+     */
+    preChatFormVisible: boolean;
+    /** Captured pre-chat submission, sent on the first chat call. */
+    preChatSubmission: PreChatSubmission | null;
+    /** Per-visitor consent. Until set explicitly, only direct launcher clicks
+     *  trigger; behavioral conditions stay dormant. */
+    consent: ConsentSettings;
+    /** ID of the trigger attributed to the next conversation start, if any. */
+    pendingTriggerId: string | null;
+    /** When set, the host should preload this text into the input. Cleared
+     *  once the host consumes it (or when the conversation starts). */
+    pendingPrefill: string | null;
 }
 
 type Listener = (state: ChatState) => void;
@@ -148,6 +295,10 @@ declare class CustomerHeroChat {
     private identityData;
     t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    private triggersRuntime;
+    private preChatFormSubmitted;
+    private readStoredConsent;
+    private writeStoredConsent;
     setLocale(tag: string): void;
     private rebuildTranslator;
     subscribe(listener: Listener): () => void;
@@ -179,6 +330,38 @@ declare class CustomerHeroChat {
     open(): void;
     close(): void;
     reset(): void;
+    /** Update visitor consent. Until `analytics: true` is set, only direct
+     *  launcher clicks fire — URL/time/scroll/exit-intent/trait conditions
+     *  stay dormant. The setting is persisted in localStorage so revisits
+     *  don't re-prompt. */
+    setConsent(consent: Partial<ConsentSettings>): void;
+    /** Set or update visitor traits used by trait-based conditions. The trait
+     *  values are kept in memory (not persisted) so the integrator decides
+     *  the source of truth. */
+    setTraits(traits: Record<string, string | number | boolean>): void;
+    /** Submit pre-chat form answers. Synthesizes a customer record server-side
+     *  on the next sendMessage. Resumes any pending message that was deferred
+     *  while the form was open. */
+    submitPreChatForm(submission: PreChatSubmission): Promise<void>;
+    /** Dismiss the pre-chat form without submitting. The form will reappear
+     *  on the next sendMessage attempt — call `setConsent` to acknowledge a
+     *  refusal, or `reset()` to clear pending state. */
+    cancelPreChatForm(): void;
+    /** Programmatically dispatch the action attached to a trigger. Used by
+     *  integrators who want to act on a custom button, e.g. an exit-intent
+     *  modal in their own UI. */
+    fireTrigger(triggerId: string): void;
+    private pendingMessageAfterPreChat;
+    private shouldShowPreChatForm;
+    private startTriggersRuntimeIfPossible;
+    private handleTriggerAction;
+    /** Read and clear the pending prefill (set by an `open_with_prefill`
+     *  trigger). The host calls this once when mounting the input and seeds
+     *  its controlled value with the result. */
+    consumePendingPrefill(): string | null;
+    /** Stop the triggers runtime and detach listeners. Safe to call multiple
+     *  times; safe to call before the runtime started. */
+    destroy(): void;
     identify(payload: IdentifyPayload): void;
 }
 
@@ -202,4 +385,57 @@ declare class ScreenshotUnavailable extends Error {
 declare function canCaptureScreenshot(): boolean;
 declare function captureScreenshot(): Promise<Blob>;
 
-export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };
+interface VisitorContext {
+    url: string;
+    queryParams: Record<string, string>;
+    referrer: string;
+    language: string;
+    device: "mobile" | "tablet" | "desktop";
+    /** Time spent on the current page (in ms). Pauses while the tab is hidden. */
+    timeOnPageMs: number;
+    /** Scroll depth as a percentage of the document height (0..100). Tracked as
+     *  a high-water mark so a quick scroll-up doesn't undo a `scroll_depth`
+     *  match. */
+    scrollPercent: number;
+    /** True after the runtime detected a desktop-style exit-intent gesture or
+     *  the mobile fallback (visibilitychange→hidden after a grace period). */
+    exitIntentSeen: boolean;
+    /** Number of distinct sessions this visitor has visited the page. */
+    returnVisitCount: number;
+    /** Custom traits set by the integrator via `setTraits` / `identify`. */
+    traits: Record<string, string | number | boolean>;
+}
+declare function evaluate(node: TriggerConditionNode, ctx: VisitorContext): boolean;
+/** Walk `triggers` in priority order (low number = high priority) and return
+ *  the first one that matches `ctx` and isn't already in `firedSet`. The
+ *  caller decides what `firedSet` means — once_ever uses long-lived storage,
+ *  once_per_session uses the in-memory or sessionStorage set, every_time
+ *  always misses the set so it can re-fire. */
+declare function pickFire(triggers: TriggerDefinition[], ctx: VisitorContext, firedSet: ReadonlySet<string>): TriggerDefinition | null;
+
+interface TriggersRuntimeHandle {
+    /** Stop all watchers and remove listeners. */
+    stop(): void;
+    /** Force a re-evaluation (used after the integrator calls setTraits). */
+    reevaluate(): void;
+    /** Update visitor traits and re-evaluate. */
+    setTraits(traits: Record<string, string | number | boolean>): void;
+    /** Mark a trigger as fired (used after a direct launcher click acted on
+     *  a trigger or when the runtime fired one itself). */
+    markFired(triggerId: string, frequency: TriggerFrequency): void;
+}
+interface StartTriggersRuntimeOptions {
+    chatbotId: string;
+    triggers: TriggerDefinition[];
+    /** Returns true when the runtime is allowed to fire a trigger. The client
+     *  uses this to gate on consent — only direct launcher clicks fire until
+     *  the integrator has called `setConsent({ analytics: true })`. */
+    isAllowedToFire(): boolean;
+    /** Called when a trigger is selected to fire. */
+    onFire(trigger: TriggerDefinition): void;
+    /** Optional initial traits seed. */
+    initialTraits?: Record<string, string | number | boolean>;
+}
+declare function startTriggersRuntime(options: StartTriggersRuntimeOptions): TriggersRuntimeHandle;
+
+export { type ActionConfirmationBlock, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, evaluate, isRtlLocale, pickFire, resolveLocale, startTriggersRuntime };

package/dist/index.d.ts

@@ -123,6 +123,133 @@ interface IdentityData {
     userHash?: string;
     customProperties?: Record<string, string | number | boolean>;
 }
+type TriggerConditionNode = {
+    all: TriggerConditionNode[];
+} | {
+    any: TriggerConditionNode[];
+} | TriggerConditionLeaf;
+type TriggerConditionLeaf = {
+    kind: "url_path";
+    op: "equals" | "contains" | "regex" | "starts_with";
+    value: string;
+} | {
+    kind: "url_query";
+    key: string;
+    op: "equals" | "contains" | "exists";
+    value?: string;
+} | {
+    kind: "referrer";
+    op: "contains" | "equals" | "regex";
+    value: string;
+} | {
+    kind: "time_on_page";
+    seconds: number;
+} | {
+    kind: "scroll_depth";
+    percent: number;
+} | {
+    kind: "exit_intent";
+} | {
+    kind: "device";
+    op: "equals";
+    value: "mobile" | "tablet" | "desktop";
+} | {
+    kind: "browser_language";
+    op: "in";
+    values: string[];
+} | {
+    kind: "visitor_trait";
+    key: string;
+    op: "equals" | "exists" | "gt" | "lt";
+    value?: string | number | boolean;
+} | {
+    kind: "return_visit";
+    op: "gte" | "eq";
+    count: number;
+};
+type TriggerAction = {
+    kind: "open_widget";
+} | {
+    kind: "send_message";
+    message: string;
+} | {
+    kind: "show_form";
+} | {
+    kind: "open_with_prefill";
+    prefill: string;
+};
+type TriggerFrequency = "once_ever" | "once_per_session" | "every_time";
+interface TriggerDefinition {
+    id: string;
+    priority: number;
+    conditions: TriggerConditionNode;
+    action: TriggerAction;
+    frequency: TriggerFrequency;
+}
+type PreChatFieldKind = "name" | "email" | "phone" | "text" | "textarea" | "select" | "consent";
+type PreChatField = {
+    kind: "name";
+    required?: boolean;
+    label?: string;
+} | {
+    kind: "email";
+    required?: boolean;
+    label?: string;
+    validateMx?: boolean;
+} | {
+    kind: "phone";
+    required?: boolean;
+    label?: string;
+} | {
+    kind: "text";
+    key: string;
+    label: string;
+    required?: boolean;
+    maxLength?: number;
+} | {
+    kind: "textarea";
+    key: string;
+    label: string;
+    required?: boolean;
+    maxLength?: number;
+} | {
+    kind: "select";
+    key: string;
+    label: string;
+    options: Array<{
+        value: string;
+        label: string;
+    }>;
+    required?: boolean;
+} | {
+    kind: "consent";
+    key: string;
+    label: string;
+    url?: string;
+    required: true;
+};
+interface PreChatFormConfig {
+    fields: PreChatField[];
+    title?: string | null;
+    description?: string | null;
+    submitLabel: string;
+    /** When true, an identified visitor (CustomerHero.identify already called)
+     *  bypasses the form. */
+    skipForIdentified: boolean;
+}
+interface PreChatSubmission {
+    name?: string;
+    email?: string;
+    phone?: string;
+    /** Keyed answers from text/textarea/select/consent fields. */
+    properties?: Record<string, string | number | boolean>;
+}
+interface ConsentSettings {
+    /** When true, all condition kinds are evaluated. When false (default), only
+     *  direct launcher clicks fire — URL/time/scroll/exit-intent/trait
+     *  conditions stay dormant. */
+    analytics: boolean;
+}
 interface ChatState {
     messages: ChatMessage[];
     isOpen: boolean;
@@ -137,6 +264,26 @@ interface ChatState {
     locale: SupportedLocale;
     /** True when the active locale is right-to-left. */
     isRtl: boolean;
+    /** Triggers loaded from the server config (active + in-window). */
+    triggers: TriggerDefinition[];
+    /** Pre-chat form configuration, if any. */
+    preChatForm: PreChatFormConfig | null;
+    /**
+     * True when the pre-chat form must be shown before the next chat turn.
+     * Flipped by trigger actions, by the first sendMessage when a form is
+     * configured and not yet submitted, and cleared on submit.
+     */
+    preChatFormVisible: boolean;
+    /** Captured pre-chat submission, sent on the first chat call. */
+    preChatSubmission: PreChatSubmission | null;
+    /** Per-visitor consent. Until set explicitly, only direct launcher clicks
+     *  trigger; behavioral conditions stay dormant. */
+    consent: ConsentSettings;
+    /** ID of the trigger attributed to the next conversation start, if any. */
+    pendingTriggerId: string | null;
+    /** When set, the host should preload this text into the input. Cleared
+     *  once the host consumes it (or when the conversation starts). */
+    pendingPrefill: string | null;
 }
 
 type Listener = (state: ChatState) => void;
@@ -148,6 +295,10 @@ declare class CustomerHeroChat {
     private identityData;
     t: TranslateFn;
     constructor(config: CustomerHeroChatConfig);
+    private triggersRuntime;
+    private preChatFormSubmitted;
+    private readStoredConsent;
+    private writeStoredConsent;
     setLocale(tag: string): void;
     private rebuildTranslator;
     subscribe(listener: Listener): () => void;
@@ -179,6 +330,38 @@ declare class CustomerHeroChat {
     open(): void;
     close(): void;
     reset(): void;
+    /** Update visitor consent. Until `analytics: true` is set, only direct
+     *  launcher clicks fire — URL/time/scroll/exit-intent/trait conditions
+     *  stay dormant. The setting is persisted in localStorage so revisits
+     *  don't re-prompt. */
+    setConsent(consent: Partial<ConsentSettings>): void;
+    /** Set or update visitor traits used by trait-based conditions. The trait
+     *  values are kept in memory (not persisted) so the integrator decides
+     *  the source of truth. */
+    setTraits(traits: Record<string, string | number | boolean>): void;
+    /** Submit pre-chat form answers. Synthesizes a customer record server-side
+     *  on the next sendMessage. Resumes any pending message that was deferred
+     *  while the form was open. */
+    submitPreChatForm(submission: PreChatSubmission): Promise<void>;
+    /** Dismiss the pre-chat form without submitting. The form will reappear
+     *  on the next sendMessage attempt — call `setConsent` to acknowledge a
+     *  refusal, or `reset()` to clear pending state. */
+    cancelPreChatForm(): void;
+    /** Programmatically dispatch the action attached to a trigger. Used by
+     *  integrators who want to act on a custom button, e.g. an exit-intent
+     *  modal in their own UI. */
+    fireTrigger(triggerId: string): void;
+    private pendingMessageAfterPreChat;
+    private shouldShowPreChatForm;
+    private startTriggersRuntimeIfPossible;
+    private handleTriggerAction;
+    /** Read and clear the pending prefill (set by an `open_with_prefill`
+     *  trigger). The host calls this once when mounting the input and seeds
+     *  its controlled value with the result. */
+    consumePendingPrefill(): string | null;
+    /** Stop the triggers runtime and detach listeners. Safe to call multiple
+     *  times; safe to call before the runtime started. */
+    destroy(): void;
     identify(payload: IdentifyPayload): void;
 }
 
@@ -202,4 +385,57 @@ declare class ScreenshotUnavailable extends Error {
 declare function canCaptureScreenshot(): boolean;
 declare function captureScreenshot(): Promise<Blob>;
 
-export { type ActionConfirmationBlock, type ChatMessage, type ChatState, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, isRtlLocale, resolveLocale };
+interface VisitorContext {
+    url: string;
+    queryParams: Record<string, string>;
+    referrer: string;
+    language: string;
+    device: "mobile" | "tablet" | "desktop";
+    /** Time spent on the current page (in ms). Pauses while the tab is hidden. */
+    timeOnPageMs: number;
+    /** Scroll depth as a percentage of the document height (0..100). Tracked as
+     *  a high-water mark so a quick scroll-up doesn't undo a `scroll_depth`
+     *  match. */
+    scrollPercent: number;
+    /** True after the runtime detected a desktop-style exit-intent gesture or
+     *  the mobile fallback (visibilitychange→hidden after a grace period). */
+    exitIntentSeen: boolean;
+    /** Number of distinct sessions this visitor has visited the page. */
+    returnVisitCount: number;
+    /** Custom traits set by the integrator via `setTraits` / `identify`. */
+    traits: Record<string, string | number | boolean>;
+}
+declare function evaluate(node: TriggerConditionNode, ctx: VisitorContext): boolean;
+/** Walk `triggers` in priority order (low number = high priority) and return
+ *  the first one that matches `ctx` and isn't already in `firedSet`. The
+ *  caller decides what `firedSet` means — once_ever uses long-lived storage,
+ *  once_per_session uses the in-memory or sessionStorage set, every_time
+ *  always misses the set so it can re-fire. */
+declare function pickFire(triggers: TriggerDefinition[], ctx: VisitorContext, firedSet: ReadonlySet<string>): TriggerDefinition | null;
+
+interface TriggersRuntimeHandle {
+    /** Stop all watchers and remove listeners. */
+    stop(): void;
+    /** Force a re-evaluation (used after the integrator calls setTraits). */
+    reevaluate(): void;
+    /** Update visitor traits and re-evaluate. */
+    setTraits(traits: Record<string, string | number | boolean>): void;
+    /** Mark a trigger as fired (used after a direct launcher click acted on
+     *  a trigger or when the runtime fired one itself). */
+    markFired(triggerId: string, frequency: TriggerFrequency): void;
+}
+interface StartTriggersRuntimeOptions {
+    chatbotId: string;
+    triggers: TriggerDefinition[];
+    /** Returns true when the runtime is allowed to fire a trigger. The client
+     *  uses this to gate on consent — only direct launcher clicks fire until
+     *  the integrator has called `setConsent({ analytics: true })`. */
+    isAllowedToFire(): boolean;
+    /** Called when a trigger is selected to fire. */
+    onFire(trigger: TriggerDefinition): void;
+    /** Optional initial traits seed. */
+    initialTraits?: Record<string, string | number | boolean>;
+}
+declare function startTriggersRuntime(options: StartTriggersRuntimeOptions): TriggersRuntimeHandle;
+
+export { type ActionConfirmationBlock, type ChatMessage, type ChatState, type ConsentSettings, CustomerHeroChat, type CustomerHeroChatConfig, DEFAULTS, type IdentifyPayload, type IdentityData, type MessageBlock, type MessageRating, type MessageSource, type MessageStatus, type PreChatField, type PreChatFieldKind, type PreChatFormConfig, type PreChatSubmission, type QuickRepliesBlock, type ResolvedConfig, SUPPORTED_LOCALES, ScreenshotCancelled, ScreenshotUnavailable, type StringOverrides, type SupportedLocale, type TranslateFn, type TranslationKey, type Translations, type TriggerAction, type TriggerConditionLeaf, type TriggerConditionNode, type TriggerDefinition, type TriggerFrequency, type TriggersRuntimeHandle, type VisitorContext, canCaptureScreenshot, captureScreenshot, createTranslator, detectLocale, evaluate, isRtlLocale, pickFire, resolveLocale, startTriggersRuntime };