@useago/sdk 1.5.2 → 1.5.3

package/dist/index.d.cts

@@ -77,6 +77,12 @@ export declare class AgoClient {
     private pendingApprovals;
     /** App-provided gate deciding WHEN a paused turn resumes (see {@link registerResumeGate}). */
     private resumeGate;
+    /**
+     * Proactive-mode controller, set when the client was created with
+     * `proactive` options or when `createAgoProactive(client, opts)` was called.
+     * `null` otherwise.
+     */
+    proactive: ProactiveController | null;
     constructor(config: AgoConfig);
     /**
      * Send a message and receive a streaming response
@@ -247,6 +253,14 @@ export declare class AgoClient {
      * Get all registered function schemas
      */
     getRegisteredFunctions(): ClientFunctionSchema[];
+    /**
+     * Execute a registered client function locally, through the same
+     * FunctionRegistry path (result-size guard, error wrapping) as agent-invoked
+     * calls. Used by proactive nudge actions, where the user's explicit click on
+     * the action button constitutes the approval — nothing is submitted to the
+     * backend (there is no tool call to answer).
+     */
+    executeClientFunction(name: string, args: Record<string, unknown>): Promise<unknown>;
     /**
      * Register a navigation function that lets AGO navigate users to different pages.
      *
@@ -348,6 +362,9 @@ export declare class AgoClient {
      */
     notifyContextChanged(): void;
     /* Excluded from this release type: emitFormEvent */
+    /* Excluded from this release type: emitProactiveEvent */
+    /* Excluded from this release type: getHttp */
+    /* Excluded from this release type: getConfiguredAgent */
     /**
      * Enable automatic capture of the current browser page (URL + title).
      * Injected as a dynamic context entry named `browser-page`.
@@ -392,6 +409,7 @@ export declare class AgoClient {
      * Clean up resources
      */
     destroy(): void;
+    /* Excluded from this release type: reviveAfterDestroy */
 }
 
 /**
@@ -508,6 +526,25 @@ export declare interface AgoClientEvents {
     "connection:status": {
         connected: boolean;
     };
+    /**
+     * A proactive nudge passed every governor gate and is ready to display.
+     * `useProactiveNudge` / `<AgoNudge>` consume this; custom UIs should call
+     * `client.proactive.shown(nudge)` when they render it (impression tracking
+     * + frequency caps), then `accept(nudge)` / `dismiss(nudge)`.
+     */
+    "nudge:ready": ProactiveNudgeInstance;
+    /** A nudge was displayed to the user (fires once per nudge). */
+    "nudge:shown": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user dismissed the nudge (its trigger is suppressed, see governor). */
+    "nudge:dismissed": {
+        nudge: ProactiveNudgeInstance;
+    };
+    /** The user accepted the nudge (its action ran / the chat is being seeded). */
+    "nudge:accepted": {
+        nudge: ProactiveNudgeInstance;
+    };
 }
 
 /**
@@ -569,6 +606,16 @@ export declare interface AgoConfig {
      * with `maxResultBytes` on its definition; `Infinity` disables the guard.
      */
     maxFunctionResultBytes?: number;
+    /**
+     * Enable the proactive mode: declarative triggers evaluated client-side
+     * against friction signals (dwell/idle time, rage clicks, route bounces…)
+     * that can surface a nudge before the user opens the chat. Equivalent to
+     * calling `createAgoProactive(client, proactive)` — the resulting controller
+     * is available as `client.proactive`. Requires the tenant-level kill-switch
+     * (`GET /api/sdk/v1/config` → `proactive.enabled`) to be on; disabled by
+     * default otherwise.
+     */
+    proactive?: ProactiveOptions;
 }
 
 /**
@@ -1044,6 +1091,35 @@ export declare const copyToClipboard: ClientFunctionDefinition;
  */
 export declare function createAgo(overrides?: Partial<AgoConfig>): AgoClient;
 
+/**
+ * Attach the proactive mode to a client: starts the signal collector, the
+ * trigger engine, and the nudge governor, and registers the aggregated
+ * friction snapshot as a dynamic context provider so the reactive mode
+ * benefits too (the agent "knows" the user hesitated on every message).
+ *
+ * ```ts
+ * const proactive = createAgoProactive(client, {
+ *   triggers: [{
+ *     id: "kyc-doc-stuck",
+ *     when: { route: "/dossier/*", idleMs: 20000, pageState: { step: "documents" } },
+ *     cooldownMs: 300_000,
+ *     intervene: "agent",
+ *     goal: "Help the user upload their KYC documents",
+ *   }],
+ *   frequencyCap: { perSession: 3, perDay: 5 },
+ * });
+ * // later: proactive.destroy();
+ * ```
+ *
+ * Also wired through the config: `new AgoClient({ ..., proactive })` attaches
+ * it automatically and exposes it as `client.proactive`.
+ *
+ * Nothing fires until the backend confirms the feature: the engine reads the
+ * `proactive.enabled` kill-switch from `GET /api/sdk/v1/config` and stays
+ * disabled by default.
+ */
+export declare function createAgoProactive(client: AgoClient, options: ProactiveOptions): ProactiveController;
+
 /**
  * Identify a returning visitor with a single, stable anon id (one id, generated
  * once and reused forever) and resume their last active thread.
@@ -1495,6 +1571,43 @@ export declare const getUserLocation: ClientFunctionDefinition;
  */
 export declare const highlightElement: ClientFunctionDefinition;
 
+/**
+ * HTTP client with authentication headers
+ */
+declare class HttpClient {
+    private baseUrl;
+    private headers;
+    constructor(config: AgoConfig);
+    /**
+     * Update configuration (e.g., JWT token)
+     */
+    updateConfig(config: Partial<AgoConfig>): void;
+    /**
+     * Make a GET request
+     */
+    get<T>(path: string): Promise<T>;
+    /**
+     * Make a POST request with JSON body.
+     *
+     * `keepalive: true` lets the request survive a page unload (used by the
+     * proactive event tracker's flush-on-hide — sendBeacon can't carry the auth
+     * headers, so it's a keepalive fetch instead).
+     */
+    post<T>(path: string, body?: unknown, options?: {
+        keepalive?: boolean;
+    }): Promise<T>;
+    /**
+     * Make a POST request and return the raw Response (for streaming)
+     */
+    postStream(path: string, body?: unknown): Promise<Response>;
+    /**
+     * Make a POST request with FormData (for file uploads)
+     */
+    postFormData(path: string, formData: FormData): Promise<Response>;
+    private request;
+    private handleErrorResponse;
+}
+
 /**
  * Check if an error is a network error that should trigger polling fallback
  */
@@ -1540,6 +1653,29 @@ declare class Logger {
 
 export declare const logger: Logger;
 
+/**
+ * Match a pathname against a trigger route pattern. Mirrors the styles the
+ * navigation function already understands (`:param` segments), plus globs:
+ *
+ * - exact: `/billing`
+ * - `:param`: `/users/:id` matches `/users/42`
+ * - `*` mid-path: matches exactly one segment (`/a/*` / `/b`)
+ * - trailing `/*`: matches one or MORE remaining segments (`/dossier/*`
+ *   matches `/dossier/1` and `/dossier/1/docs`, not `/dossier`)
+ * - `*` alone matches everything
+ *
+ * Trailing slashes on the pathname are tolerated.
+ */
+export declare function matchesRoutePattern(pattern: string, pathname: string): boolean;
+
+/**
+ * Evaluate a trigger's `when` clause against a signals snapshot. Pure
+ * conjunction: every specified matcher must pass. Numeric fields are `>=`
+ * thresholds; `pageState` is a partial deep match; `fieldErrors` are per-name
+ * minimum counts.
+ */
+export declare function matchesWhen(when: ProactiveTriggerWhen, snapshot: SignalsSnapshot): boolean;
+
 export declare type MessageStatus = "IN_PROGRESS" | "DONE" | "ERROR" | "TODO" | "CANCELED"
 /**
 * The turn paused on client function call(s) (pause mode): the agent waits for
@@ -1578,6 +1714,21 @@ export declare interface MockAgoClientOptions {
 
 declare type MockFn = (...args: any[]) => any;
 
+/**
+ * Optional action attached to a nudge. Accepting a `functionName` action
+ * executes the registered client function (same `FunctionRegistry` path as
+ * agent-invoked calls); `setPageState` applies values through the registered
+ * page-state controls.
+ */
+export declare type NudgeAction = {
+    label: string;
+    functionName: string;
+    arguments?: Record<string, unknown>;
+} | {
+    label: string;
+    setPageState: Record<string, unknown>;
+};
+
 /**
  * Subscribe to failed form collector submissions (network/server failures).
  */
@@ -1641,6 +1792,13 @@ export declare function onToolCall(client: AgoClient, callback: (toolCall: ToolC
  */
 export declare const openUrl: ClientFunctionDefinition;
 
+/**
+ * Partial deep match: every key/value present in `expected` must match the
+ * corresponding value in `actual`. Nested objects recurse (partially); arrays
+ * and primitives compare by deep equality.
+ */
+export declare function partialDeepMatch(expected: unknown, actual: unknown): boolean;
+
 export declare interface PersistOptions {
     /** Key under which the state is JSON-serialized. */
     key: string;
@@ -1648,6 +1806,196 @@ export declare interface PersistOptions {
     storage?: StorageLike;
 }
 
+/**
+ * Controller returned by {@link createAgoProactive} (also available as
+ * `client.proactive`).
+ */
+export declare interface ProactiveController {
+    /** Persistently opt this browser out of proactive nudges. */
+    optOut(): void;
+    /** Undo {@link optOut}. */
+    optIn(): void;
+    isOptedOut(): boolean;
+    /**
+     * Tell the governor the user is already engaged (e.g. the chat widget is
+     * open) — nudges are suppressed while `true`. Call from the UI layer.
+     */
+    setEngaged(engaged: boolean): void;
+    /** App-pushed field error counter (field NAME only — never values). */
+    signalFieldError(fieldName: string): void;
+    /** Current aggregated friction snapshot. */
+    getSignalsSnapshot(): SignalsSnapshot;
+    /** The nudge currently occupying the single-nudge slot, if any. */
+    getActiveNudge(): ProactiveNudgeInstance | null;
+    /**
+     * Mark the nudge as displayed. Idempotent per nudge; counts it against the
+     * frequency caps, tracks the impression, and emits `nudge:shown`.
+     */
+    shown(nudge: ProactiveNudgeInstance): void;
+    /**
+     * Accept the nudge: run its action (if any), emit `nudge:accepted`, track,
+     * and — for agent nudges or nudges with a `goal` — pre-seed the chat with a
+     * hidden kickoff message so the agent starts the turn with full context.
+     */
+    accept(nudge: ProactiveNudgeInstance): Promise<void>;
+    /** Dismiss the nudge: suppress the trigger, track, emit `nudge:dismissed`. */
+    dismiss(nudge: ProactiveNudgeInstance): void;
+    /** Report a downstream conversion attributable to the nudge (analytics only). */
+    markConverted(nudge: ProactiveNudgeInstance): void;
+    /** Detach everything: listeners, timers, context provider, event flush. */
+    destroy(): void;
+}
+
+/**
+ * Response of `POST {baseUrl}/api/sdk/v1/proactive/evaluate` (snake_case, as
+ * on the wire). On 429 or any error the SDK treats the call as
+ * `intervene: false`, silently (debug log only).
+ */
+export declare interface ProactiveEvaluateResponse {
+    intervene: boolean;
+    message: string | null;
+    action: {
+        label: string;
+        function_name: string;
+        arguments?: Record<string, unknown>;
+    } | null;
+    /** Server-generated nudge uuid. */
+    nudge_id: string;
+}
+
+/** A concrete nudge produced by the engine, carried by every `nudge:*` event. */
+export declare interface ProactiveNudgeInstance {
+    /** Client-generated uuid for this nudge instance (`client_nudge_id`). */
+    id: string;
+    triggerId: string;
+    /** `static` = configured message; `agent` = backend LLM evaluation. */
+    source: "static" | "agent";
+    message: string;
+    action?: NudgeAction;
+    goal?: string;
+    /** See {@link ProactiveTrigger.kickoff}. */
+    kickoff?: string;
+    createdAt: Date;
+    /** Server-side nudge id (agent nudges only). */
+    serverNudgeId?: string;
+}
+
+/** Options for {@link createAgoProactive} / `AgoConfig.proactive`. */
+export declare interface ProactiveOptions {
+    triggers: ProactiveTrigger[];
+    /**
+     * Global caps on nudges actually shown. `perSession` is in-memory (page
+     * lifetime); `perDay` is persisted in localStorage with a date rollover —
+     * best-effort by design (private browsing resets it); the costly LLM path is
+     * additionally capped server-side.
+     */
+    frequencyCap?: {
+        perSession?: number;
+        perDay?: number;
+    };
+    /** Evaluation tick, ms. Default 1000. Zero network per tick. */
+    tickMs?: number;
+    /** Storage backend for persisted governance state. Default `localStorage`. */
+    storage?: StorageLike;
+    /** Storage key for persisted governance state. Default `"ago_proactive"`. */
+    storageKey?: string;
+    /** Tuning of the signal detectors (rage-click window, throttles…). */
+    signals?: SignalCollectorTuning;
+    /**
+     * Local demos and tests ONLY: bypass the remote kill-switch. When set, the
+     * `GET /config` fetch is skipped and the kill-switch takes this value.
+     * Leave unset in production — the tenant admin controls the feature, and
+     * the evaluate endpoint stays gated server-side regardless.
+     */
+    enabledOverride?: boolean;
+}
+
+/** One entry of the `POST {baseUrl}/api/sdk/v1/proactive/events` batch. */
+export declare interface ProactiveTrackedEvent {
+    clientNudgeId: string;
+    triggerId: string;
+    source: "static" | "agent";
+    type: "shown" | "dismissed" | "accepted" | "converted";
+    /** Nudge text, optional. */
+    message?: string;
+    /** Epoch ms; serialized as ISO-8601 `occurred_at`. */
+    occurredAt: number;
+}
+
+/** A declarative proactive trigger. */
+export declare interface ProactiveTrigger {
+    /** Stable id, used for cooldowns, dismissal memory, and analytics. */
+    id: string;
+    /** Conjunction of matchers (see {@link ProactiveTriggerWhen}). */
+    when: ProactiveTriggerWhen;
+    /**
+     * Min time between two firings of this trigger (persisted across reloads).
+     * A firing is the moment the trigger passes the gates — including an agent
+     * evaluation that decides NOT to intervene, so a persistent condition can't
+     * hammer the evaluate endpoint. Default 60 000.
+     */
+    cooldownMs?: number;
+    /**
+     * `'agent'` asks the backend's fast-LLM second filter whether (and how) to
+     * intervene; a `static` object shows the given message with no network call.
+     */
+    intervene: "agent" | {
+        type: "static";
+        message: string;
+        action?: NudgeAction;
+    };
+    /**
+     * What the agent should help with. Sent to the evaluate endpoint, and used to
+     * pre-seed the chat turn when the user accepts the nudge.
+     */
+    goal?: string;
+    /**
+     * User-voice line used to OPEN the conversation when the user accepts this
+     * nudge and no conversation exists yet — a hidden kickoff cannot start one
+     * (the backend rejects it). Sent as a visible user message, so write it in
+     * the app's language ("Oui, aidez-moi à choisir !"). When a conversation is
+     * already open, the SDK sends a hidden meta kickoff instead and this field
+     * is unused. Without it, accepting with no open conversation skips the chat
+     * pre-seed (the nudge action still runs).
+     */
+    kickoff?: string;
+    /**
+     * How long a dismissal of this trigger's nudge suppresses it (persisted).
+     * Default 24h.
+     */
+    resurfaceAfterMs?: number;
+}
+
+/**
+ * Conditions of a proactive trigger. Pure conjunction: EVERY specified matcher
+ * must pass against the current {@link SignalsSnapshot}. Numeric fields are
+ * `>=` thresholds.
+ */
+export declare interface ProactiveTriggerWhen {
+    /**
+     * Route pattern the current pathname must match. Supports the SDK's route
+     * styles: exact (`/billing`), `:param` segments (`/users/:id`), single-segment
+     * wildcards (`/a/*` / `/b`), and a trailing `/*` that matches one or more
+     * remaining segments (`/dossier/*`).
+     */
+    route?: string;
+    /** Min time since the last user activity, ms. */
+    idleMs?: number;
+    /** Min time spent on the current route, ms. */
+    dwellMs?: number;
+    /**
+     * Partial deep match against the registered page state (funnel step,
+     * filters…). Every key present here must deep-match the live value.
+     */
+    pageState?: Partial<Record<string, unknown>>;
+    /** Min rage-click bursts on the current route. */
+    rageClicks?: number;
+    /** Min A→B→A→B route oscillations this session. */
+    routeBounces?: number;
+    /** Per-field minimum error counts (field NAME → min count). */
+    fieldErrors?: Record<string, number>;
+}
+
 /**
  * Registered function with handler
  */
@@ -1739,6 +2087,168 @@ export declare const showNotification: ClientFunctionDefinition;
  */
 export declare const showToast: ClientFunctionDefinition;
 
+/** One entry of the collector's ring buffer. */
+export declare interface Signal {
+    type: SignalType;
+    /** Pathname the signal happened on. */
+    route: string;
+    /** Epoch ms. */
+    at: number;
+    /** Optional counter (e.g. how many errors this field has produced so far). */
+    count?: number;
+    /** Small, PII-free metadata (field names, previous route…). */
+    meta?: Record<string, string | number>;
+}
+
+/**
+ * Framework-agnostic collector of client-side friction signals: per-route
+ * dwell time, idle time, route bounces (A→B→A→B), rage clicks, and app-pushed
+ * field error counters. Attached to an `AgoClient` by `createAgoProactive`,
+ * the same way `ClientContextRegistry` is attached.
+ *
+ * Route observation is poll-on-demand rather than a `history.pushState` patch:
+ * the SDK must never mutate host globals (see CLAUDE.md scoping rules), so the
+ * current pathname is (re)checked on `popstate`/`hashchange`, on throttled user
+ * activity, and on every `getSnapshot()` — the proactive engine's ~1s tick
+ * makes that an effective 1s poll, plenty for multi-second dwell thresholds.
+ *
+ * Privacy: only enums, counters, and paths are recorded. Field VALUES are never
+ * read — `signalFieldError(fieldName)` takes the field name only.
+ *
+ * Listeners are passive and throttled, attached only by `start()` (i.e. only
+ * when proactive mode is configured) and fully removed by `destroy()`.
+ */
+export declare class SignalCollector {
+    private readonly getPageState?;
+    private readonly activityThrottleMs;
+    private readonly rageClickCount;
+    private readonly rageClickWindowMs;
+    private readonly rageClickRadiusPx;
+    private readonly maxRecentRoutes;
+    private readonly maxSignals;
+    private started;
+    private teardowns;
+    private route;
+    private routeEnteredAt;
+    private lastActivityAt;
+    private lastHeavyActivityAt;
+    private recentRoutes;
+    private routeBounces;
+    private rageClicks;
+    private fieldErrors;
+    private recentClicks;
+    private signals;
+    private listeners;
+    constructor(options?: SignalCollectorOptions);
+    /**
+     * Attach the DOM listeners and start tracking. Idempotent; no-op outside a
+     * browser (SSR).
+     */
+    start(): void;
+    /** Remove every listener and reset transient buffers. */
+    destroy(): void;
+    /**
+     * App-pushed signal: a form field produced a (repeated) validation error.
+     * Pass the field NAME only — values are never read, so no PII is collected.
+     */
+    signalFieldError(fieldName: string): void;
+    /**
+     * Subscribe to raw signals (route changes, bounces, rage clicks, field
+     * errors). Returns an unsubscribe function. Used by the proactive engine to
+     * evaluate promptly instead of waiting for the next tick.
+     */
+    subscribe(listener: (signal: Signal) => void): () => void;
+    /** The typed-signal ring buffer (most recent last, bounded). */
+    getSignals(): Signal[];
+    /**
+     * Aggregated snapshot of the current friction state. Re-checks the route
+     * first, so calling this on a periodic tick doubles as the route poll.
+     *
+     * `pageState: false` skips the page-state read — used by the
+     * `friction_signals` dynamic context provider, both because page state
+     * already rides in `client_context` under its own `page-state:*` entries and
+     * because reading it from inside a context provider would recurse.
+     */
+    getSnapshot(opts?: {
+        pageState?: boolean;
+    }): SignalsSnapshot;
+    private currentPathname;
+    private readPageState;
+    private recordActivity;
+    /** Compare the live pathname with the tracked one; handle a route change. */
+    private checkRoute;
+    private onClick;
+    /** Cheap fingerprint of the page state, for "did this click change anything". */
+    private pageStateKey;
+    private pushSignal;
+}
+
+export declare interface SignalCollectorOptions extends SignalCollectorTuning {
+    /**
+     * Reads the current page state (the registered `AgoStateControl.get()`
+     * snapshot). Wired by `createAgoProactive` to the client's `page-state:*`
+     * dynamic context entries so funnel state is available to trigger matchers
+     * without new plumbing.
+     */
+    getPageState?: () => Record<string, unknown> | null;
+}
+
+/** Tuning knobs for the collector's detectors. All optional. */
+export declare interface SignalCollectorTuning {
+    /** Min gap between heavy activity work (route checks, notifications), ms. Default 250. */
+    activityThrottleMs?: number;
+    /** Rage click: clicks needed to count a burst. Default 3. */
+    rageClickCount?: number;
+    /** Rage click: max time between first and last click of a burst, ms. Default 1000. */
+    rageClickWindowMs?: number;
+    /** Rage click: max radius between clicks of a burst, px. Default 24. */
+    rageClickRadiusPx?: number;
+    /** Max routes kept in the recent-route sequence. Default 10. */
+    maxRecentRoutes?: number;
+    /** Max typed signals kept in the ring buffer. Default 50. */
+    maxSignals?: number;
+}
+
+/**
+ * Aggregated view of the current friction state. Registered as a dynamic
+ * context provider (key `friction_signals`) so it rides along as
+ * `client_context` on every message, and sent as `signals` to the proactive
+ * evaluate endpoint.
+ */
+export declare interface SignalsSnapshot {
+    /** Current pathname. */
+    route: string;
+    /** Time spent on the current route, ms. */
+    dwellMs: number;
+    /** Time since the last user activity (pointer/key/scroll/touch), ms. */
+    idleMs: number;
+    /** Rage-click bursts detected on the current route. */
+    rageClicks: number;
+    /**
+     * A→B→A→B route oscillations detected in the recent route sequence. Rolling
+     * session counter (cross-route by nature); trigger cooldowns and dismissal
+     * memory keep it from re-firing forever.
+     */
+    routeBounces: number;
+    /** App-pushed field error counters (field NAME → count), current route only. */
+    fieldErrors: Record<string, number>;
+    /** Most recent pathnames, oldest first (bounded). */
+    recentRoutes: string[];
+    /**
+     * Merged `AgoStateControl.get()` snapshot of the registered page-state
+     * controls (funnel step, filters…), or `null` when none are registered.
+     */
+    pageState: Record<string, unknown> | null;
+}
+
+/**
+ * Typed friction signals collected client-side by the {@link SignalCollector}.
+ *
+ * Privacy rule: signals carry **enums, counters, and paths only** — never field
+ * values or free text — so no PII ever leaves the page through this channel.
+ */
+export declare type SignalType = "route_change" | "route_bounce" | "rage_click" | "field_error";
+
 /**
  * SSE stream chunk data
  */