@guidelytech/sdk-core 0.9.0 → 0.11.0

package/dist/index.d.cts

@@ -1,17 +1,19 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
-export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-zM5e3loY.cjs';
-export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-zM5e3loY.cjs';
-export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.cjs';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-C3faAYb7.cjs';
+import { AgentTurnInput } from '@guidelytech/shared/runtime';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
+import { m as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, n as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-Mtlmlj5C.cjs';
+export { A as AgentTurnRedactor, E as EventQueue, b as EventQueueOptions, o as GuideStepInfo, d as GuidelyEnvironment, q as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, g as countsTowardThrottle, i as isExclusiveGuide, j as isFrequencyEligible, k as isThrottleEligible, l as isWithinSchedule, p as pruneLaunches } from './types-Mtlmlj5C.cjs';
+export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-sbP9JwTE.cjs';
+export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-CgN69Lxq.cjs';
+import './http-Cb6KYYFv.cjs';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.11.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -24,6 +26,10 @@ declare class GuidelyClient {
     private readonly sessionStore;
     private readonly emitter;
     private readonly queue;
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    private readonly outbox;
+    /** Agent Analytics turns (agentConversation), in their own outbox. */
+    private readonly agentTurns;
     private config;
     private etag;
     private anonymousId;
@@ -72,6 +78,10 @@ declare class GuidelyClient {
     readonly flags: FlagsClient;
     /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
     private exposures;
+    /** Language set with `setLocale()`. */
+    private locale;
+    /** Language each shown guide was rendered in; added to its events as `locale`. */
+    private guideLocales;
     constructor(options: GuidelyOptions);
     private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
@@ -85,6 +95,8 @@ declare class GuidelyClient {
     private wireErrorListeners;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
+    /** Re-renders after a config change (refresh, or a config that arrived after start). */
+    private applyConfigChange;
     /** Tears everything down: guides, widgets, listeners, timers, host element. Re-init is allowed via a new client. */
     destroy(): void;
     /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */
@@ -104,8 +116,18 @@ declare class GuidelyClient {
     private enqueue;
     /** Tracks a custom event. Events drive `event` triggers, `advanceOn: "event"` steps and checklist tasks. */
     track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Agent Analytics: records one or more turns of a conversation with your own AI agent or chatbot
+     * (`{ conversationId, agentId, role, text, toolCalls?, latencyMs?, outcome?, … }`). The visitor's
+     * anonymous id, user id, account id and session id are filled in, `agents.redact` from the init
+     * options runs on each turn, and turns are retried until Guidely accepts them. Returns false when
+     * nothing was queued (analytics off or consent denied, or every turn was invalid or dropped).
+     */
+    agentConversation(turns: AgentTurnInput | AgentTurnInput[]): boolean;
+    /** Alias of {@link agentConversation}. */
+    trackAgentTurn(turns: AgentTurnInput | AgentTurnInput[]): boolean;
     /** Records a page view and re-evaluates triggers. Called automatically on SPA navigation. */
-    page(url?: string): void;
+    page(href?: string): void;
     private readonly customListeners;
     private readonly eventBus;
     private handleNavigation;
@@ -155,9 +177,27 @@ declare class GuidelyClient {
     isRecording(): boolean;
     /** The current analytics session id (rotates after inactivity; also the replay id). */
     getSessionId(): string;
+    /** The page URL Guidely works with: `options.pageUrl`, else app-relative for `file:` / custom protocols (`normalizeAppUrl`). */
+    pageHref(href?: string): string;
     /** Builds the targeting context for the current moment. */
     getContext(): TargetingContext;
     private isTargeted;
+    /** Guide throttling: may this guide launch automatically now? */
+    private throttleAllows;
+    private recordLaunch;
+    /** Guides and A/B test control groups, which are evaluated the same way but never render. */
+    private candidates;
+    private holdoutFor;
+    /** The visitor's language candidates, most preferred first. */
+    private locales;
+    private defaultLocale;
+    /** The guide in the visitor's language (remembered so its events carry `locale`). */
+    private localize;
+    /**
+     * Sets the language for guides and the resource center (`null` = back to the traits / browser).
+     * Guides already on screen keep their language; the resource center re-renders.
+     */
+    setLocale(locale: string | null): void;
     private isEligible;
     private triggerFires;
     private evaluate;
@@ -184,6 +224,8 @@ declare class GuidelyClient {
     /** What the messenger personalises from, computed fresh on every render. */
     private messengerVisitor;
     private destroyMessenger;
+    /** The resource center's language for this visitor, or null for the default language. */
+    private rcLocale;
     private loadArticle;
     private searchResourceCenter;
     /** Current progress for a checklist guide (by id or key). */
@@ -214,11 +256,22 @@ declare class GuidelyClient {
     /** Opens the Scout messenger (when enabled for the project), optionally on a tab. */
     openMessenger(tab?: MessengerTab): void;
     closeMessenger(): void;
+    /**
+     * Opens a Guidely prototype test (its `/validate/<token>` URL on this SDK's API origin, or the bare
+     * token) in a full-screen overlay, attributed to the current user. Returns false, doing nothing, for
+     * any other URL. Guide buttons that open a test URL use this automatically.
+     */
+    openPrototypeTest(urlOrToken: string): boolean;
     /**
      * Opens the complaint form in the messenger, optionally with a category picked (its id from
      * Complaints → Categories). Does nothing when the project doesn't take complaints.
      */
     openComplaint(categoryId?: string): void;
+    /**
+     * Opens the Ideas tab in the messenger (feature requests and voting), or one idea by its id.
+     * Does nothing when the project hasn't turned on Ideas.
+     */
+    openIdeas(requestId?: string): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
     /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
@@ -330,6 +383,10 @@ type Listener = (url: string) => void;
  */
 declare function watchNavigation(listener: Listener, debounceMs?: number): () => void;
 
+declare function normalizeAppUrl(href: string): string;
+/** True for desktop-shell URLs (`file:`, custom protocols such as `app:`), which {@link normalizeAppUrl} makes app-relative. */
+declare function isAppUrl(href: string): boolean;
+
 declare const AUTHORING_PARAM = "guidely_authoring";
 declare const HEARTBEAT_MS = 15000;
 /** Messages the SDK posts to the dashboard window (`window.opener`). */
@@ -419,6 +476,22 @@ interface PageLeaveInfo {
     scrollDepth: number;
 }
 
+/**
+ * In-app recruitment for Guidely prototype tests (Validate). A guide button that opens a Guidely test URL
+ * (`<apiOrigin>/validate/<token>`, same origin as the SDK's API) shows the test in a full-screen overlay
+ * iframe instead of navigating away. Attribution (public key, anonymous id, user id) goes in the URL
+ * fragment, so it never reaches servers, proxies or logs; the test page reads and clears it.
+ *
+ * The overlay is a modal dialog: focus moves into it and is trapped between the close button and the
+ * test frame, Escape closes it, and it closes when the test page posts `{ type: "guidely:prototype:close" }`.
+ */
+declare const PROTOTYPE_CLOSE_MESSAGE = "guidely:prototype:close";
+/**
+ * The test URL for a full test URL or a bare token, when it points at this Guidely deployment's
+ * `/validate/<token>` page; null for anything else (other origins and paths keep their normal behaviour).
+ */
+declare function matchPrototypeTestUrl(urlOrToken: string, apiUrl: string): URL | null;
+
 /**
  * @guidelytech/sdk-core — framework-independent Guidely browser SDK.
  *
@@ -434,4 +507,4 @@ declare const Guidely: {
     version: string;
 };
 
-export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, watchNavigation };
+export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };

package/dist/index.d.ts

@@ -1,17 +1,19 @@
 import * as _guidelytech_guide_runtime from '@guidelytech/guide-runtime';
 import { TargetingContext, PublishedGuide, ProjectTheme, SelectorStrategy, AuthoringPick, AppSnapshot } from '@guidelytech/shared';
-export { AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
+export { AgentEventsResponse, AgentOutcome, AgentToolCallInput, AgentTurnInput, AgentTurnRole, AppSnapshot, AutocaptureSettings, ExceptionProperties, GuideConfig, GuideStep, PublishedGuide, SdkConfigResponse, SdkEvent, StackFrame, TargetingContext } from '@guidelytech/shared';
 import { FlagsClient, JsonValue, FlagValue, FlagDetails } from '@guidelytech/flags';
 export { Attributes, EvaluationResult, FlagDetails, FlagsBootstrap, FlagsClient, FlagsClientOptions, FlagsPayload, JsonValue } from '@guidelytech/flags';
 import { MessengerTab } from '@guidelytech/guide-runtime/messenger';
-import { k as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, l as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-DnJW_4ck.js';
-export { E as EventQueue, b as EventQueueOptions, m as GuideStepInfo, d as GuidelyEnvironment, n as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, i as isExclusiveGuide, h as isFrequencyEligible, j as isWithinSchedule } from './types-DnJW_4ck.js';
-export { K as KEYS, b as KeyValueStore, S as StorageKind, d as createStorage } from './http-47tiAlOM.js';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-Dqd7up2n.js';
+import { AgentTurnInput } from '@guidelytech/shared/runtime';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
+import { m as GuidelyOptions, c as GuidelyAccount, a as ConsentState, C as ChecklistProgressState, n as GuidelyEvents, e as GuidelyUser, G as GuideLocalState, S as SessionState } from './types-BDlebXrm.js';
+export { A as AgentTurnRedactor, E as EventQueue, b as EventQueueOptions, o as GuideStepInfo, d as GuidelyEnvironment, q as GuidelyEventName, P as PersistedState, f as areMutuallyExclusive, g as countsTowardThrottle, i as isExclusiveGuide, j as isFrequencyEligible, k as isThrottleEligible, l as isWithinSchedule, p as pruneLaunches } from './types-BDlebXrm.js';
+export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-sbP9JwTE.js';
+export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-Csz721-A.js';
+import './http-D047Ngxk.js';
 
 declare const SDK_NAME = "@guidelytech/sdk-core";
-declare const SDK_VERSION = "0.9.0";
+declare const SDK_VERSION = "0.11.0";
 declare const DEFAULT_API_URL = "https://api.guidely.app";
 /**
  * Framework-independent Guidely client. Create one per page with {@link createGuidely} or
@@ -24,6 +26,10 @@ declare class GuidelyClient {
     private readonly sessionStore;
     private readonly emitter;
     private readonly queue;
+    /** Survey answers and guide/checklist progress, kept until the server accepts them. */
+    private readonly outbox;
+    /** Agent Analytics turns (agentConversation), in their own outbox. */
+    private readonly agentTurns;
     private config;
     private etag;
     private anonymousId;
@@ -72,6 +78,10 @@ declare class GuidelyClient {
     readonly flags: FlagsClient;
     /** Experiments already reported this session (`experiment_viewed` is sent once per session). */
     private exposures;
+    /** Language set with `setLocale()`. */
+    private locale;
+    /** Language each shown guide was rendered in; added to its events as `locale`. */
+    private guideLocales;
     constructor(options: GuidelyOptions);
     private createFlags;
     /** Loads config (cache first, then network), wires listeners and evaluates triggers. Idempotent. */
@@ -85,6 +95,8 @@ declare class GuidelyClient {
     private wireErrorListeners;
     /** Re-fetches the published config and re-evaluates triggers. */
     refresh(): Promise<void>;
+    /** Re-renders after a config change (refresh, or a config that arrived after start). */
+    private applyConfigChange;
     /** Tears everything down: guides, widgets, listeners, timers, host element. Re-init is allowed via a new client. */
     destroy(): void;
     /** Identifies the end user and loads server-held state (audiences, guide history, checklist progress). */
@@ -104,8 +116,18 @@ declare class GuidelyClient {
     private enqueue;
     /** Tracks a custom event. Events drive `event` triggers, `advanceOn: "event"` steps and checklist tasks. */
     track(name: string, properties?: Record<string, unknown>): void;
+    /**
+     * Agent Analytics: records one or more turns of a conversation with your own AI agent or chatbot
+     * (`{ conversationId, agentId, role, text, toolCalls?, latencyMs?, outcome?, … }`). The visitor's
+     * anonymous id, user id, account id and session id are filled in, `agents.redact` from the init
+     * options runs on each turn, and turns are retried until Guidely accepts them. Returns false when
+     * nothing was queued (analytics off or consent denied, or every turn was invalid or dropped).
+     */
+    agentConversation(turns: AgentTurnInput | AgentTurnInput[]): boolean;
+    /** Alias of {@link agentConversation}. */
+    trackAgentTurn(turns: AgentTurnInput | AgentTurnInput[]): boolean;
     /** Records a page view and re-evaluates triggers. Called automatically on SPA navigation. */
-    page(url?: string): void;
+    page(href?: string): void;
     private readonly customListeners;
     private readonly eventBus;
     private handleNavigation;
@@ -155,9 +177,27 @@ declare class GuidelyClient {
     isRecording(): boolean;
     /** The current analytics session id (rotates after inactivity; also the replay id). */
     getSessionId(): string;
+    /** The page URL Guidely works with: `options.pageUrl`, else app-relative for `file:` / custom protocols (`normalizeAppUrl`). */
+    pageHref(href?: string): string;
     /** Builds the targeting context for the current moment. */
     getContext(): TargetingContext;
     private isTargeted;
+    /** Guide throttling: may this guide launch automatically now? */
+    private throttleAllows;
+    private recordLaunch;
+    /** Guides and A/B test control groups, which are evaluated the same way but never render. */
+    private candidates;
+    private holdoutFor;
+    /** The visitor's language candidates, most preferred first. */
+    private locales;
+    private defaultLocale;
+    /** The guide in the visitor's language (remembered so its events carry `locale`). */
+    private localize;
+    /**
+     * Sets the language for guides and the resource center (`null` = back to the traits / browser).
+     * Guides already on screen keep their language; the resource center re-renders.
+     */
+    setLocale(locale: string | null): void;
     private isEligible;
     private triggerFires;
     private evaluate;
@@ -184,6 +224,8 @@ declare class GuidelyClient {
     /** What the messenger personalises from, computed fresh on every render. */
     private messengerVisitor;
     private destroyMessenger;
+    /** The resource center's language for this visitor, or null for the default language. */
+    private rcLocale;
     private loadArticle;
     private searchResourceCenter;
     /** Current progress for a checklist guide (by id or key). */
@@ -214,11 +256,22 @@ declare class GuidelyClient {
     /** Opens the Scout messenger (when enabled for the project), optionally on a tab. */
     openMessenger(tab?: MessengerTab): void;
     closeMessenger(): void;
+    /**
+     * Opens a Guidely prototype test (its `/validate/<token>` URL on this SDK's API origin, or the bare
+     * token) in a full-screen overlay, attributed to the current user. Returns false, doing nothing, for
+     * any other URL. Guide buttons that open a test URL use this automatically.
+     */
+    openPrototypeTest(urlOrToken: string): boolean;
     /**
      * Opens the complaint form in the messenger, optionally with a category picked (its id from
      * Complaints → Categories). Does nothing when the project doesn't take complaints.
      */
     openComplaint(categoryId?: string): void;
+    /**
+     * Opens the Ideas tab in the messenger (feature requests and voting), or one idea by its id.
+     * Does nothing when the project hasn't turned on Ideas.
+     */
+    openIdeas(requestId?: string): void;
     /** Opens a new messenger conversation, optionally pre-filling the message. */
     showNewMessage(text?: string): void;
     /** Boolean flag value for the current user; `fallback` (default `false`) until loaded or when missing. */
@@ -330,6 +383,10 @@ type Listener = (url: string) => void;
  */
 declare function watchNavigation(listener: Listener, debounceMs?: number): () => void;
 
+declare function normalizeAppUrl(href: string): string;
+/** True for desktop-shell URLs (`file:`, custom protocols such as `app:`), which {@link normalizeAppUrl} makes app-relative. */
+declare function isAppUrl(href: string): boolean;
+
 declare const AUTHORING_PARAM = "guidely_authoring";
 declare const HEARTBEAT_MS = 15000;
 /** Messages the SDK posts to the dashboard window (`window.opener`). */
@@ -419,6 +476,22 @@ interface PageLeaveInfo {
     scrollDepth: number;
 }
 
+/**
+ * In-app recruitment for Guidely prototype tests (Validate). A guide button that opens a Guidely test URL
+ * (`<apiOrigin>/validate/<token>`, same origin as the SDK's API) shows the test in a full-screen overlay
+ * iframe instead of navigating away. Attribution (public key, anonymous id, user id) goes in the URL
+ * fragment, so it never reaches servers, proxies or logs; the test page reads and clears it.
+ *
+ * The overlay is a modal dialog: focus moves into it and is trapped between the close button and the
+ * test frame, Escape closes it, and it closes when the test page posts `{ type: "guidely:prototype:close" }`.
+ */
+declare const PROTOTYPE_CLOSE_MESSAGE = "guidely:prototype:close";
+/**
+ * The test URL for a full test URL or a bare token, when it points at this Guidely deployment's
+ * `/validate/<token>` page; null for anything else (other origins and paths keep their normal behaviour).
+ */
+declare function matchPrototypeTestUrl(urlOrToken: string, apiUrl: string): URL | null;
+
 /**
  * @guidelytech/sdk-core — framework-independent Guidely browser SDK.
  *
@@ -434,4 +507,4 @@ declare const Guidely: {
     version: string;
 };
 
-export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, watchNavigation };
+export { AUTHORING_PARAM, type AuthoringIncomingMessage, type AuthoringOutgoingMessage, ChecklistProgressState, type ClickProperties, ConsentState, type ContextInput, DEFAULT_API_URL, type DeviceInfo, GuideLocalState, Guidely, GuidelyAccount, GuidelyClient, GuidelyEvents, GuidelyOptions, GuidelyUser, HEARTBEAT_MS, PROTOTYPE_CLOSE_MESSAGE, type PageLeaveInfo, SDK_NAME, SDK_VERSION, SessionState, buildContext, captureSnapshot, createGuidely, Guidely as default, detectDevice, isAppUrl, matchPrototypeTestUrl, normalizeAppUrl, watchNavigation };