@guidelytech/sdk-core 0.10.0 → 0.11.0

package/dist/index.d.cts

@@ -1,18 +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-B5ecgHUV.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-B5ecgHUV.cjs';
-export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DFHUstWd.cjs';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-DVJyQ2JZ.cjs';
+import { AgentTurnInput } from '@guidelytech/shared/runtime';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
-import './http-D0dCcpLN.cjs';
+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.10.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
@@ -27,6 +28,8 @@ declare class GuidelyClient {
     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;
@@ -75,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. */
@@ -109,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;
@@ -160,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;
@@ -189,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). */
@@ -219,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. */
@@ -335,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`). */
@@ -424,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.
  *
@@ -439,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,18 +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-BtPovimB.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-BtPovimB.js';
-export { a as KEYS, K as KeyValueStore, c as StorageKind, d as createStorage } from './health-DFHUstWd.js';
-export { C as CaptureMarker, a as CaptureOutgoingMessage } from './capture-369s4YYT.js';
+import { AgentTurnInput } from '@guidelytech/shared/runtime';
 export { CAPTURE_PARAM } from '@guidelytech/shared/runtime';
-import './http-DJd8jRhK.js';
+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.10.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
@@ -27,6 +28,8 @@ declare class GuidelyClient {
     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;
@@ -75,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. */
@@ -109,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;
@@ -160,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;
@@ -189,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). */
@@ -219,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. */
@@ -335,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`). */
@@ -424,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.
  *
@@ -439,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 };